Webhooks - BNPL Issuance

Summary

After a successful issuance response, you will receive webhooks notifying you about the events in the operation lifecycle: contract signature, disbursement, and eventually cancellation.

Attention!

Webhooks should not be strictly mapped. New fields may be added to the payload without prior notice.

Signature Webhook

This webhook is sent when the contract (CCB) is successfully signed.

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"
}

Signature Webhook Fields

Field	Type	Description
key	string	Unique debt key (DEBT-KEY)
status	string	Event status: signature_finished
webhook_type	string	Webhook type: debt
event_datetime	string	Event date and time
signed_contract_url	string	URL of the signed contract (PDF)

Disbursement Webhook

This webhook confirms that the disbursement was successfully completed.

WEBHOOK_TYPE

debt

STATUS

disbursed

Webhook Body

{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
        "installments": [
            {
                "due_date": "2025-11-27",
                "total_amount": 87.43,
                "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
                "pre_fixed_amount": 29.26477451,
                "installment_number": 1,
                "principal_amortization_amount": 58.16522549
            },
            {
                "due_date": "2025-12-27",
                "total_amount": 87.43,
                "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
                "pre_fixed_amount": 20.11446867,
                "installment_number": 2,
                "principal_amortization_amount": 67.31553133
            },
            {
                "due_date": "2026-01-27",
                "total_amount": 87.43,
                "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
                "pre_fixed_amount": 11.07075682,
                "installment_number": 3,
                "principal_amortization_amount": 76.35924318
            }
        ],
        "ted_receipt_list": [],
        "requester_identifier_key": null
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T17:10:21Z"
}

Disbursement Webhook Fields

Field	Type	Description
key	string	Unique debt key (DEBT-KEY)
status	string	Event status: disbursed
webhook_type	string	Webhook type: debt
event_datetime	string	Event date and time
data.installments	array	List of installments with their keys and amounts
data.ted_receipt_list	array	List of TED receipts (when applicable)

Cancellation Webhook

If the debt fails to disburse, or is returned, you will receive a cancellation webhook.

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"
}

Cancellation Webhook Fields

Field	Type	Description
key	string	Unique debt key (DEBT-KEY)
status	string	Event status: canceled
webhook_type	string	Webhook type: debt
event_datetime	string	Event date and time
data.cancel_reason	string	Textual description of the cancellation reason
data.cancel_reason_enumerator	string	Cancellation reason enumerator

Cancellation Enumerators

Enumerator	Description
disbursing_error	Operation canceled due to an error during disbursement
waiting_signature	Operation canceled due to missing signature
pix_max_retry	Operation canceled because the receiving bank could not process the disbursement
manual	Operation canceled manually
agencia_conta_invalida	Invalid agency or recipient account number
invalid_account	The destination account number is nonexistent or invalid
invalid_document_number	The CPF/CNPJ of the destination account is incorrect
unsupported_transaction	The destination account does not support this type of transaction
invalid_ispb	The ISPB number is invalid or nonexistent
rejected_payment	Payment order was rejected by the receiving bank
refund_after_payee_request	Refund requested by the payee
blocked_account	The destination account is blocked
amount_too_great	Payment/refund amount exceeds the limit for the credited destination account
receiver_error	Transaction interrupted due to error on the receiver's PSP
closed_account	The destination account is closed
disbursing_hour_closed	Disbursement occurred outside of the allowed time frame
unregistered_pix_key	The Pix key is not registered
spi_timeout	Timeout control in SPI