Skip to main content

Pix refund sent Webhook

info

📘 To learn more about webhooks in our API, follow the link below:

About Webhooks

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.

warning

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​

NameDescription
x-delbank-api-keyRequired. 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:

NameDescription
statusThe status of the refund PIX transaction
errorObject containing information about the error
error.codeInternal code given to the error
error.descriptionDescription of what caused the error to trigger
eventTypeThe type of event that triggered the webhook (e.g., "PIX_REFUND_PAYMENT_ERROR").
operationTypeThe type of operation being performed
endToEndIdThe unique identifier for the refund Pix transaction.
originalEndToEndIdThe unique identifier for the original Pix transaction that is being refunded.
idempotencyKeyA unique key to ensure idempotency of the event processing.
correlationIdThe transaction's correlationId
amountThe monetary value of the refund Pix transaction.
createdAtThe timestamp indicating when the refund Pix transaction was created.
descriptionA textual description explaining the reason for the refund (e.g., "Pedido reembolso").
payerAn object containing information about the payer of the refund PIX transaction.
payer.numberThe account number of the payer.
payer.branchThe branch number of the payer's account.
payer.typeThe type of the payer's account (e.g., "CURRENT").
payer.participantAn object containing information about the financial institution of the payer.
payer.participant.ispbThe ISPB code of the payer's financial institution (e.g., "38224857").
payer.holderAn object containing information about the holder of the payer's account.
payer.holder.nameThe name of the payer (e.g., "EMPRESA LTDA").
payer.holder.documentThe document number of the payer (e.g., "94478450000138").
payer.holder.typeThe type of payer (e.g., "LEGAL").
beneficiaryAn object containing information about the beneficiary of the refund PIX transaction.
beneficiary.numberThe account number of the beneficiary.
beneficiary.branchThe branch number of the beneficiary's account.
beneficiary.typeThe type of the beneficiary's account (e.g., "PAYMENT").
beneficiary.participantAn object containing information about the financial institution of the beneficiary.
beneficiary.participant.ispbThe ISPB code of the beneficiary's financial institution (e.g., "1111111111").
beneficiary.holderAn object containing information about the holder of the beneficiary's account.
beneficiary.holder.documentThe document number of the beneficiary (e.g., partially masked for security).
beneficiary.holder.typeThe type of beneficiary (e.g., "NATURAL" or "LEGAL").
payeeAn object containing information about the payee of the refund PIX transaction.
payee.numberThe account number of the payee.
payee.branchThe branch number of the payee's account.
payee.typeThe type of the payee's account (e.g., "PAYMENT").
payee.participantAn object containing information about the financial institution of the payee.
payee.participant.ispbThe ISPB code of the payee's financial institution (e.g., "1111111111").
payee.holderAn object containing information about the holder of the payee's account.
payee.holder.documentThe document number of the payee (e.g., partially masked for security).
payee.holder.typeThe type of payee (e.g., "NATURAL" or "LEGAL").