Pix refund sent Webhook

info

📘 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.

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

Name	Description
x-delbank-api-key	Required. API key
x-delfinance-account-id	Required. The Delfinance bank account number

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").

Headers​

Body​

Headers

Body