Webhooks - Emissão BNPL

Resumo

Após a resposta de sucesso da emissão, você receberá webhooks notificando sobre os eventos do ciclo de vida da operação: assinatura do contrato, desembolso e, eventualmente, cancelamento.

Atenção!

Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.

Webhook de Assinatura

Este webhook é enviado quando o contrato (CCB) é assinado com sucesso.

WEBHOOK_TYPE

debt

STATUS

signature_finished

Webhook Body

{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T17:09:33Z",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/CCB-TIK11267101212-20251027170925_signed.pdf"
}

Campos do Webhook de Assinatura

Campo	Tipo	Descrição
key	string	Chave única da dívida (DEBT-KEY)
status	string	Status do evento: signature_finished
webhook_type	string	Tipo do webhook: debt
event_datetime	string	Data e hora do evento
signed_contract_url	string	URL do contrato assinado (PDF)

Webhook de Desembolso

Este webhook confirma que o desembolso foi realizado com sucesso.

WEBHOOK_TYPE

debt

STATUS

disbursed

Webhook Body

{
    "key": "132372de-fead-488f-9fae-b6c2986182be",
    "data": {
      "installments": [
        {
          "due_date": "2026-04-27",
          "total_amount": 89.48,
          "installment_key": "470c69cd-2a3e-4a17-9003-819e9d37a510",
          "pre_fixed_amount": 5.60437824,
          "installment_number": 1,
          "principal_amortization_amount": 83.87562176
        },
        {
          "due_date": "2026-05-26",
          "total_amount": 89.48,
          "installment_key": "c190c72d-2ea8-478c-b85b-041c0f402a0c",
          "pre_fixed_amount": 8.00493898,
          "installment_number": 2,
          "principal_amortization_amount": 81.47506102
        },
        {
          "due_date": "2026-06-26",
          "total_amount": 89.48,
          "installment_key": "07c40e11-400d-4675-8a57-b9bee9e4b21c",
          "pre_fixed_amount": 6.90959582,
          "installment_number": 3,
          "principal_amortization_amount": 82.57040418
        },
        {
          "due_date": "2026-07-27",
          "total_amount": 89.48,
          "installment_key": "43dfc3ec-99ed-4b86-9105-a126c69ca1ea",
          "pre_fixed_amount": 5.23461479,
          "installment_number": 4,
          "principal_amortization_amount": 84.24538521
        },
        {
          "due_date": "2026-08-26",
          "total_amount": 89.48,
          "installment_key": "104c9564-488c-44f4-ba50-5c1e87c145a7",
          "pre_fixed_amount": 3.4109145,
          "installment_number": 5,
          "principal_amortization_amount": 86.0690855
        },
        {
          "due_date": "2026-09-28",
          "total_amount": 89.48,
          "installment_key": "aa073681-d11c-4349-ad4a-64f68538447c",
          "pre_fixed_amount": 1.89555767,
          "installment_number": 6,
          "principal_amortization_amount": 87.58444233
        }
      ],
      "ted_receipt_list": [
        {
          "fee": 0,
          "url": "https://storage.googleapis.com/sandbox-doc-api/documents/491e-b208-ddf5addab58d/1043ce73-b366-491e-ddf5addab58d.pdf",
          "amount": 500.0,
          "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000135",
            "bank_code": "329",
            "account_key": "5d068423-6094-49e4-b15b-7740038295a8",
            "branch_digit": null,
            "account_digit": "5",
            "account_branch": "0001",
            "account_number": "00002",
            "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
          },
          "timestamp": "2026-04-10T14:48:35",
          "description": "00360305 0001 12345-6 12345678000199 - NEXUS TECH SOLUTIONS",
          "destination": {
            "name": "NEXUS TECH SOLUTIONS",
            "type": "checking_account",
            "branch": "0001",
            "purpose": "Crédito PIX em Conta",
            "document": "12345678000199",
            "bank_ispb": "00360305",
            "branch_digit": null,
            "account_digit": "6",
            "account_number": "12345",
            "financial_institution_name": "BANCO HORIZONTE S.A."
          },
          "end_to_end_id": "E00360305202604151954bB7qwX9pzKL0",
          "transaction_key": "2fb21861-b43c-4bbc-85d8-ece2aaf6328e",
          "origin_transaction_key": "dbd8af8d-c372-4d1b-8d9a-24527286d80a"
        }
      ],
      "requester_identifier_key": "65caad48-976c-44ea-8e34-c8519241981d"
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2026-04-10 14:48:35"
  }

Campos do Webhook de Desembolso

Campo	Tipo	Descrição
key	string	Chave única da dívida (DEBT-KEY)
status	string	Status do evento: disbursed
webhook_type	string	Tipo do webhook: debt
event_datetime	string	Data e hora do evento
data.installments	array	Lista de parcelas com suas chaves e valores
data.ted_receipt_list	array	Lista de comprovantes de TED (quando aplicável)

Webhook de Cancelamento

Se a dívida falhar no desembolso ou for devolvida, você receberá um webhook de cancelamento.

WEBHOOK_TYPE

debt

STATUS

canceled

Webhook Body

{
    "webhook_type": "debt",
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "event_datetime": "2025-10-27T16:38:59Z",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
    "status": "canceled"
}

Campos do Webhook de Cancelamento

Campo	Tipo	Descrição
key	string	Chave única da dívida (DEBT-KEY)
status	string	Status do evento: canceled
webhook_type	string	Tipo do webhook: debt
event_datetime	string	Data e hora do evento
data.cancel_reason	string	Descrição textual do motivo do cancelamento
data.cancel_reason_enumerator	string	Enumerador do motivo do cancelamento

Enumeradores de Cancelamento

Enumerador	Descrição
disbursing_error	Operação cancelada por erro durante o desembolso
waiting_signature	Operação cancelada por falta de assinatura
pix_max_retry	Operação cancelada porque o banco receptor não processou o desembolso
manual	Operação cancelada manualmente
agencia_conta_invalida	Agência ou número de conta do destinatário inválidos
invalid_account	Número da conta de destino inexistente ou inválido
invalid_document_number	CPF/CNPJ da conta de destino incorreto
unsupported_transaction	A conta de destino não suporta este tipo de transação
invalid_ispb	O número ISPB é inválido ou inexistente
rejected_payment	Ordem de pagamento rejeitada pelo banco receptor
refund_after_payee_request	Estorno solicitado pelo beneficiário
blocked_account	A conta de destino está bloqueada
amount_too_great	Valor excede o limite da conta de destino
receiver_error	Transação interrompida por erro no PSP do receptor
closed_account	A conta de destino está encerrada
disbursing_hour_closed	Desembolso fora do horário permitido
unregistered_pix_key	A chave Pix não está registrada
spi_timeout	Timeout no controle SPI