Documentação
Status PageSuporte
  1. cel_banking - BaaS & Core
  2. Open Finance as a Service
  3. Pagamentos Automáticos

Callback e Execução de Pagamento Pix

Parte 1 — Callback do Consentimento

Visão Geral

Após o usuário aprovar o consentimento na detentora, ele é redirecionado de volta à redirectUrl da ITP com code, id_token e state. A ITP envia esses parâmetros ao endpoint de callback para finalizar a autorização e ativar o consentimento.

O endpoint de callback é compartilhado com o Pix Instantâneo — o state e o paymentInitiationApi identificam o produto correto internamente.

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

Autenticação: Bearer Token (application_token)

Request

POST {{base_url}}/baas/v1/open/itp/payment-initiation/callback
Authorization: Bearer {{application_token}}
Content-Type: application/json
{
  "code": "{{callback_code}}",
  "id_token": "{{callback_id_token}}",
  "state": "{{callback_state}}"
}
CampoTipoObrigatórioDescrição
codestring✅Authorization code recebido na redirectUrl
id_tokenstring✅ID Token JWT recebido na redirectUrl
statestring✅Correlaciona o callback à payment initiation correta (equivale ao itp_payment_id)

Response — HTTP 200 (Sucesso)

{
  "brandId": "66f4d9e296f18bc4606e1618",
  "id": "6a3d1e159c0f8d0011779569",
  "paymentInitiationApi": "AUTOMATIC_PAYMENTS_V2",
  "ofConsent": {
    "consentId": "urn:bricks-demo:f4b0c161-f5f6-4adb-ae63-21a2160238d0",
    "status": "AUTHORISED",
    "recurringConsentId": "urn:bricks-demo:f4b0c161-f5f6-4adb-ae63-21a2160238d0",
    "debtorAccount": {
      "ispb": "12345678",
      "issuer": "0001",
      "number": "969139",
      "accountType": "CACC"
    }
  },
  "journeySession": {
    "status": "AUTHORISED"
  }
}
CampoTipoDescrição
idstringID da payment initiation — usar como itp_payment_id nos pagamentos
ofConsent.statusstringAUTHORISED — consentimento ativo para receber pagamentos
ofConsent.debtorAccountobjectConta devedora selecionada pelo usuário na detentora

Códigos de Retorno

HTTPDescrição
200 OKCallback processado e consentimento autorizado
400 Bad RequestParâmetros inválidos ou ausentes
401 UnauthorizedToken de aplicação inválido
422 Unprocessable Entitycode expirado, state não encontrado ou consentimento rejeitado

Parte 2 — Executar Pagamento Pix Recorrente

Visão Geral

Com o consentimento em status AUTHORISED, a ITP envia cada cobrança individualmente ao endpoint de pagamentos. Cada chamada representa um ciclo da recorrência (ex: a cobrança do mês de julho). O pagamento é recebido com RCVD e processado de forma assíncrona pela detentora.

POST /baas/v1/open/itp/automatic-payments/payment-initiation/:paymentInitiationId/payments

Autenticação: Bearer Token (application_token)

Path Parameters

ParâmetroTipoObrigatórioDescrição
paymentInitiationIdstring✅ID da payment initiation (itp_payment_id)

Request

POST {{base_url}}/baas/v1/open/itp/automatic-payments/payment-initiation/{{itp_payment_id}}/payments
Authorization: Bearer {{application_token}}
Content-Type: application/json
{
  "data": {
    "date": "2026-06-25",
    "proxy": "11111111000111",
    "localInstrument": "AUTO",
    "remittanceInformation": "Cobrança mensal - contrato XE00038166",
    "document": {
      "identification": "11111111000111",
      "rel": "CNPJ"
    },
    "cnpjInitiator": "13935893000109",
    "payment": {
      "amount": "150.00",
      "currency": "BRL"
    },
    "endToEndId": "E13935893202606250431HnY18krNL5P",
    "creditorAccount": {
      "ispb": "12345678",
      "issuer": "1774",
      "number": "1234567890",
      "accountType": "CACC"
    },
    "riskSignals": {
      "automatic": {
        "lastLoginDateTime": "2026-06-24T14:30:45Z",
        "pixKeyRegistrationDateTime": "2026-01-10T09:00:00Z"
      }
    },
    "paymentReference": "R/2026-05-22/P1W"
  }
}

Campos do Request

CampoTipoObrigatórioDescrição
data.datestring (YYYY-MM-DD)✅Data de liquidação do pagamento. Deve respeitar a periodicidade do consentimento
data.proxystring✅Chave Pix do recebedor
data.localInstrumentstring✅Fixo: AUTO para Pix Automático
data.remittanceInformationstring❌Descrição do pagamento (até 140 caracteres)
data.cnpjInitiatorstring✅CNPJ da ITP iniciadora
data.payment.amountstring✅Valor em BRL (duas casas decimais). Deve estar entre minimumVariableAmount e maximumVariableAmount, ou igual a fixedAmount
data.payment.currencystring✅Fixo: BRL
data.endToEndIdstring✅Identificador end-to-end único da transação Pix. Ver formato abaixo
data.paymentReferencestring✅Referência da recorrência. Formato: R/{referenceStartDate}/{interval_ISO}

data.document

CampoTipoObrigatórioDescrição
identificationstring✅CPF ou CNPJ do pagador
relstring✅CPF ou CNPJ

data.creditorAccount

CampoTipoObrigatórioDescrição
ispbstring✅ISPB da instituição recebedora (8 dígitos)
issuerstring✅Agência do recebedor
numberstring✅Número da conta do recebedor
accountTypestring✅CACC, SVGS, SLRY ou TRAN

data.riskSignals.automatic

CampoTipoObrigatórioDescrição
lastLoginDateTimestring (ISO 8601)✅Data e hora do último login do pagador na plataforma da ITP
pixKeyRegistrationDateTimestring (ISO 8601)✅Data e hora do registro da chave Pix utilizada

Formato do endToEndId

E{ISPB_iniciadora}{YYYYMMDD}{HHMM}{11_chars_aleatorios}

Exemplo: E13935893202606250431HnY18krNL5P

ComponenteTamanhoDescrição
E1Prefixo fixo
ISPB8ISPB da ITP (sem separadores)
YYYYMMDD8Data da transação
HHMM4Hora e minuto (0000 para agendamentos)
Aleatório11Sufixo alfanumérico único
Total32—

Formato do paymentReference

O paymentReference identifica a referência temporal da recorrência:

R/{referenceStartDate}/{periodicidade_ISO8601}
IntervaloCódigo ISOExemplo
DIARIOP1DR/2026-05-22/P1D
SEMANALP1WR/2026-05-22/P1W
MENSALP1MR/2026-05-22/P1M
SEMESTRALP6MR/2026-05-22/P6M
ANUALP1YR/2026-05-22/P1Y

Response — HTTP 201

{
  "data": {
    "recurringPaymentId": "pmt-rec-abc123def456",
    "endToEndId": "E13935893202606250431HnY18krNL5P",
    "status": "RCVD",
    "amount": "150.00",
    "currency": "BRL",
    "date": "2026-06-25",
    "paymentReference": "R/2026-05-22/P1W",
    "createdAt": "2026-06-25T10:00:00Z"
  }
}
CampoTipoDescrição
data.recurringPaymentIdstringID único do pagamento recorrente. Usar em retentativas e cancelamentos
data.statusstringStatus inicial: RCVD (requisição recebida pela detentora)

Códigos de Retorno

HTTPDescrição
201 CreatedPagamento recebido para processamento
401 UnauthorizedToken inválido ou expirado
404 Not FoundpaymentInitiationId não encontrado
422 Unprocessable EntityConsentimento não AUTHORISED, valor fora dos limites, data inválida

Pontos de Atenção

⚠️

localInstrument deve ser AUTO: Outros valores causam rejeição imediata. Este campo identifica que o pagamento é do tipo automático recorrente.

⚠️

amount deve respeitar os limites do consentimento: Para valor variável, deve estar entre minimumVariableAmount e maximumVariableAmount. Para valor fixo, deve ser exatamente fixedAmount. Divergências retornam RJCT com reason PAGAMENTO_DIVERGENTE_CONSENTIMENTO.

⚠️

endToEndId único por pagamento: Cada ciclo de pagamento exige um endToEndId diferente. Reutilizar o mesmo ID causa erro de duplicidade no SPI.

⚠️

riskSignals obrigatório: Os campos lastLoginDateTime e pixKeyRegistrationDateTime são sinais anti-fraude obrigatórios para pagamentos automáticos. Use sempre valores reais — não utilize datas estáticas em produção.

⚠️

RCVD ≠ liquidado: O status inicial indica que a detentora recebeu o pedido. A liquidação efetiva (ACSC) ou rejeição (RJCT) é assíncrona. Monitore via webhook.

⚠️

code expira rapidamente: Chame o endpoint de callback imediatamente após receber o redirect. Atrasos causam erros invalid_request_uri.