Response Payload Scenarios for Webhooks 🚧

This article describes the different response payload scenarios for cash in and cash out operations in the context of webhooks. Each scenario is described with JSON payload examples for better understanding.

1. Cash In

This scenario occurs when there is a receipt of funds. The webhook payload contains information about the transaction and the involved account details.

Webhook Registration Endpoint - /webhook/{chave}

Configure Pix Webhook

Payload Example:

JSON

{
  "data": {
    "id": 9876543210,
    "txId": "a9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4",
    "pixKey": "12345abc-de67-890f-gh12-3456789ijklm",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "123.45",
      "currency": "BRL"
    },
    "refunds": [],
    "createdAt": "2024-09-01T12:30:00.000Z",
    "errorCode": null,
    "endToEndId": "E12345678901234567890123456789012",
    "ticketData": {},
    "webhookType": "RECEIVE",
    "debtorAccount": {
      "ispb": "12345678",
      "name": "Fictitious Bank",
      "issuer": "5678",
      "number": "123456789",
      "document": "12345678901",
      "accountType": "CACC"
    },
    "idempotencyKey": null,
    "creditDebitType": "CREDIT",
    "creditorAccount": {
      "ispb": "87654321",
      "name": "Fictitious Finance - LTDA",
      "issuer": "8765",
      "number": "987654321",
      "document": "98765432100",
      "accountType": "TRAN"
    },
    "localInstrument": "QRDN",
    "transactionType": "PIX",
    "remittanceInformation": null
  },
  "type": "RECEIVE"
}

 

2. Cash Out

This scenario occurs when there is an outgoing fund transfer. The webhook payload reflects the debit operation on the source account.

Webhook Registration Endpoint - /webhooks/transfer

Create Webhooks for Transfer Operations

JSON

{
  "data": {  
    "id": 1122334455,  
    "txId": null,  
    "pixKey": "12345678901",  
    "status": "LIQUIDATED",  
    "payment": {  
      "amount": "200.50",  
      "currency": "BRL"  
    },  
    "refunds": [],  
    "createdAt": "2024-09-01T14:45:30.000Z",  
    "errorCode": null,  
    "endToEndId": "E12345678901234567890123456789013",  
    "ticketData": {},  
    "webhookType": "TRANSFER",  
    "debtorAccount": {  
      "ispb": "87654321",  
      "name": "Fictitious Finance - LTDA",  
      "issuer": "8765",  
      "number": "987654321",  
      "document": "98765432100",  
      "accountType": "TRAN"  
    },  
    "idempotencyKey": "abcd1234",  
    "creditDebitType": "DEBIT",  
    "creditorAccount": {  
      "ispb": "12345678",  
      "name": "Fictitious Bank",  
      "issuer": "5678",  
      "number": "123456789",  
      "document": "12345678901",  
      "accountType": "CACC"  
    },  
    "localInstrument": "DICT",  
    "transactionType": "PIX",  
    "remittanceInformation": null  
  },  
  "type": "TRANSFER"  
}

3.1 Refund

This scenario occurs when a refund is processed. The payload includes details of the original transaction and the refund transaction.

Refund Endpoint - /webhooks/refund

Create Webhooks for Refund Operations

JSON

{
  "data": {
    "id": 9988776655,
    "txId": null,
    "pixKey": "98765432100",
    "status": "REFUNDED",
    "payment": {
      "amount": "150.75",
      "currency": "BRL"
    },
    "refunds": [
      {
        "status": "LIQUIDATED",
        "payment": {
          "amount": 150.75,
          "currency": "BRL"
        },
        "errorCode": null,
        "eventDate": "2024-09-01T15:30:45.000Z",
        "endToEndId": "D87654321202409011530XyZ4567AbCd",
        "information": "Devolução solicitada pelo cliente"
      }
    ],
    "createdAt": "2024-09-01T15:00:00.000Z",
    "errorCode": null,
    "endToEndId": "E12345678202409011500ZyX1234AbCd",
    "ticketData": {},
    "webhookType": "REFUND",
    "debtorAccount": {
      "ispb": "87654321",
      "name": "Fictitious Finance - LTDA",
      "issuer": "8765",
      "number": "987654321",
      "document": "98765432100",
      "accountType": "TRAN"
    },
    "idempotencyKey": "efgh5678",
    "creditDebitType": "DEBIT",
    "creditorAccount": {
      "ispb": "12345678",
      "name": "Fictitious Bank",
      "issuer": "5678",
      "number": "123456789",
      "document": "12345678901",
      "accountType": "CACC"
    },
    "localInstrument": "DICT",
    "transactionType": "PIX",
    "remittanceInformation": null
  },
  "type": "REFUND"
}

4. Cash Out Error

This scenario occurs when there is an error during a transfer operation. The webhook payload describes the error that occurred.

JSON

{
  "data": {
    "status": "REJECTED",
    "message": "Saldo insuficiente para realizar transação.",
    "createdAt": "2024-09-01T16:45:58.634+00:00",
    "endToEndId": "E12345678202409011645467890123456",
    "webhookType": "CASHOUT",
    "idempotencyKey": "abcd124"
  },
  "type": "CASHOUT",
  "transaction": {
    "status": "REJECTED",
    "message": "Saldo insuficiente para realizar transação.",
    "reference": "abcd124"
  }
}

Example Payload - Pix Key Not Found:

JSON

{
  "data": {
    "status": "REJECTED",
    "message": "Chave Pix não encontrada",
    "createdAt": "2024-09-01T17:41:30.538+00:00",
    "endToEndId": "E98765432202409011741876543210987",
    "webhookType": "CASHOUT",
    "idempotencyKey": "efgh1242"
  },
  "type": "CASHOUT",
  "transaction": {
    "status": "REJECTED",
    "message": " ",
    "reference": "efgh1242"
  }
}