Pix refund sent Webhook
📘 To learn more about webhooks in our API, follow the link below:
When a Pix payment is credited to your account and a refund is issued, the best way to receive updates about any potential errors is through the PIX_REFUND_PAYMENT_UPDATED webhook. If an error occurs during the refund process, the transaction status will be updated, and a PIX_REFUND_PAYMENT_UPDATED webhook will be triggered.
Please note that this webhook is specifically for errors related to Pix refunds. For successful Pix payments — including sent Pix refunds — the PIX_PAYMENT_UPDATED
webhook is used
Here's the simplest way to configure a PIX_REFUND_PAYMENT_UPDATED
webhook:
Headers​
Name | Description |
---|---|
x-delbank-api-key | Required. API key |
Body​
{
"eventType": "PIX_REFUND_PAYMENT_UPDATED",
"url": "https://example.com.br/webhooks/v1/pixrefundsent", // Add your own URL here
"authorization": "NONE,
"authorizationScheme": "NONE"
}
Here's an example of a webhook of an error on a sent Pix refund:
{
"status": "PIX_ERROR",
"error": {
"code": "DEL20",
"description": "Pix original ainda não foi processado."
},
"eventType": "PIX_REFUND_PAYMENT_ERROR",
"endToEndId": "D38224857202505151236QaPfJMQyyRj",
"idempotencyKey": "E38224857202505151235EU6L6UCKIAM",
"correlationId": null,
"amount": 0.01,
"createdAt": "2025-05-15T12:36:48",
"finishedAt": "2025-05-15T12:36:48",
"description": null,
"payer": null,
"beneficiary": null
}
Here are the attributes that can be passed by the PIX_REFUND_PAYMENT_UPDATED
webhook:
Name | Description |
---|---|
status | The status of the refund PIX transaction |
error | Object containing information about the error |
error.code | Internal code given to the error |
error.description | Description of what caused the error to trigger |
eventType | The type of event that triggered the webhook (e.g., "PIX_REFUND_PAYMENT_ERROR"). |
operationType | The type of operation being performed |
endToEndId | The unique identifier for the refund Pix transaction. |
originalEndToEndId | The unique identifier for the original Pix transaction that is being refunded. |
idempotencyKey | A unique key to ensure idempotency of the event processing. |
correlationId | The transaction's correlationId |
amount | The monetary value of the refund Pix transaction. |
createdAt | The timestamp indicating when the refund Pix transaction was created. |
description | A textual description explaining the reason for the refund (e.g., "Pedido reembolso"). |
payer | An object containing information about the payer of the refund PIX transaction. |
payer.number | The account number of the payer. |
payer.branch | The branch number of the payer's account. |
payer.type | The type of the payer's account (e.g., "CURRENT"). |
payer.participant | An object containing information about the financial institution of the payer. |
payer.participant.ispb | The ISPB code of the payer's financial institution (e.g., "38224857"). |
payer.holder | An object containing information about the holder of the payer's account. |
payer.holder.name | The name of the payer (e.g., "EMPRESA LTDA"). |
payer.holder.document | The document number of the payer (e.g., "94478450000138"). |
payer.holder.type | The type of payer (e.g., "LEGAL"). |
beneficiary | An object containing information about the beneficiary of the refund PIX transaction. |
beneficiary.number | The account number of the beneficiary. |
beneficiary.branch | The branch number of the beneficiary's account. |
beneficiary.type | The type of the beneficiary's account (e.g., "PAYMENT"). |
beneficiary.participant | An object containing information about the financial institution of the beneficiary. |
beneficiary.participant.ispb | The ISPB code of the beneficiary's financial institution (e.g., "1111111111"). |
beneficiary.holder | An object containing information about the holder of the beneficiary's account. |
beneficiary.holder.document | The document number of the beneficiary (e.g., partially masked for security). |
beneficiary.holder.type | The type of beneficiary (e.g., "NATURAL" or "LEGAL"). |
payee | An object containing information about the payee of the refund PIX transaction. |
payee.number | The account number of the payee. |
payee.branch | The branch number of the payee's account. |
payee.type | The type of the payee's account (e.g., "PAYMENT"). |
payee.participant | An object containing information about the financial institution of the payee. |
payee.participant.ispb | The ISPB code of the payee's financial institution (e.g., "1111111111"). |
payee.holder | An object containing information about the holder of the payee's account. |
payee.holder.document | The document number of the payee (e.g., partially masked for security). |
payee.holder.type | The type of payee (e.g., "NATURAL" or "LEGAL"). |