Documentação
Status PageSuporte
  1. cel_banking - BaaS & Core
  2. Open Finance as a Service
  3. Pix Instantâneo - ITP (Jornada com Redirecionamento)

ITP - Criar Consentimento (Payment Initiation)

Visão Geral

A payment initiation é o objeto que representa a intenção de pagamento do usuário. Ela contém os dados do pagador, do recebedor e do valor a ser transferido. Após criada, retorna uma authorizationUrl para onde o usuário deve ser redirecionado para autenticar e aprovar o pagamento na sua instituição.

Cada payment initiation corresponde a um único pagamento Pix.

Criar Payment Initiation

POST /baas/v1/open/itp/payment-initiation

Autenticação: Bearer Token (application_token)

Request

POST {{base_url}}/baas/v1/open/itp/payment-initiation
Authorization: Bearer {{application_token}}
Content-Type: application/json
{
  "brandId": "6900de69dfdf118e980e10ec",
  "redirectUrl": "http://localhost:8080/callback",
  "data": {
    "loggedUser": {
      "document": {
        "identification": "12345678909",
        "rel": "CPF"
      }
    },
    "creditor": {
      "cpfCnpj": "58764789000137",
      "personType": "PESSOA_JURIDICA",
      "name": "Marco Antonio de Brito"
    },
    "payment": {
      "type": "PIX",
      "amount": "1.15",
      "currency": "BRL",
      "date": "2026-05-31",
      "details": {
        "localInstrument": "DICT",
        "proxy": "12345678901",
        "creditorAccount": {
          "accountType": "CACC",
          "ispb": "12345678",
          "issuer": "1774",
          "number": "1234567890"
        }
      }
    }
  }
}

Campos do Request

Nível raiz

CampoTipoObrigatórioDescrição
brandIdstring✅ID da instituição detentora, obtido em Participantes
redirectUrlstring✅URL de callback para retorno após autorização do usuário

data.loggedUser.document

CampoTipoObrigatórioDescrição
identificationstring✅CPF do usuário pagador (somente números, 11 dígitos)
relstring✅Tipo do documento. Fixo: CPF

data.creditor

CampoTipoObrigatórioDescrição
cpfCnpjstring✅CPF (11 dígitos) ou CNPJ (14 dígitos) do recebedor
personTypestring✅PESSOA_NATURAL ou PESSOA_JURIDICA
namestring✅Nome completo do recebedor

data.payment

CampoTipoObrigatórioDescrição
typestring✅Tipo de pagamento. Fixo: PIX
amountstring✅Valor em BRL com duas casas decimais (ex: "1.15")
currencystring✅Moeda. Fixo: BRL
datestring✅Data de liquidação (formato YYYY-MM-DD). Deve ser hoje ou data futura

data.payment.details

CampoTipoObrigatórioDescrição
localInstrumentstring✅Modalidade de iniciação. Ver tabela abaixo
proxystring❌Chave Pix do recebedor. Obrigatório quando localInstrument = DICT

data.payment.details.creditorAccount

CampoTipoObrigatórioDescrição
accountTypestring✅Tipo de conta: CACC (corrente), SVGS (poupança), SLRY (salário), TRAN (pagamento)
ispbstring✅ISPB da instituição recebedora (8 dígitos)
issuerstring✅Número da agência
numberstring✅Número da conta

data.debtorAccount (opcional)

Quando informado, pré-seleciona a conta devedora na detentora:

CampoTipoObrigatórioDescrição
accountTypestring❌Tipo de conta do pagador
ispbstring❌ISPB da instituição devedora
issuerstring❌Agência do pagador
numberstring❌Número da conta do pagador

Modalidades de Iniciação (localInstrument)

ValorDescriçãoproxy obrigatório?
DICTChave Pix (CPF, CNPJ, e-mail, telefone ou chave aleatória)✅
MANUDados manuais da conta (sem chave Pix)❌
QRDNQR Code dinâmico❌
QRESQR Code estático❌
INICIniciação pela ITP❌

Response — HTTP 201

{
  "authorizationUrl": "https://openfinance.dev.fbank.opb.obm.engdev.fsapps.io/orgs/finansystech/auth?client_id=4f-BSI7qe1iD_5B82NfF3&scope=openid%20consent%3A...&response_type=code%20id_token&redirect_uri=...&request_uri=...",
  "id": "ZVjnvOXJSlgth9MVDS4HmdvyhBlHt_s1MPhMNMBhGSU"
}
CampoTipoDescrição
authorizationUrlstringURL para redirecionamento do usuário. Contém client_id, scope, request_uri e demais parâmetros FAPI
idstringID da payment initiation. Usar como itp_payment_id nas chamadas subsequentes

Response — HTTP 422 (Erro de data)

{
  "errors": [
    {
      "code": "DATA_PAGAMENTO_INVALIDA",
      "title": "Data de pagamento inválida.",
      "detail": "Data de pagamento inválida para a forma de pagamento selecionada."
    }
  ]
}

Códigos de Retorno

HTTPDescrição
201 CreatedConsentimento criado com sucesso
400 Bad RequestParâmetros ausentes ou malformados
401 UnauthorizedToken inválido ou expirado
422 Unprocessable EntityData inválida, dados do creditor inconsistentes ou regra de negócio violada

Pontos de Atenção

⚠️

date deve ser hoje ou futuro: Datas passadas retornam 422 DATA_PAGAMENTO_INVALIDA. Sempre gere a data dinamicamente no momento da criação.

⚠️

Guarde o id retornado: O id da payment initiation é necessário para o endpoint de Pix (/payment-initiation/:id/pix). Salve-o imediatamente após a criação.

⚠️

A authorizationUrl é de uso único e expira rapidamente: Após recebê-la, redirecione o usuário imediatamente. Tentar reutilizar a URL ou chamá-la após alguns minutos retornará 302 com error=invalid_request_uri.

⚠️

proxy + DICT: Quando localInstrument = DICT, o campo proxy é obrigatório e deve conter uma chave Pix válida do recebedor. Omitir este campo causará erro de validação.

⚠️

redirectUrl em produção: Deve ser HTTPS e estar pré-registrada. Em sandbox, http://localhost:8080/callback é aceita.


Updated about 2 hours ago