Pular para o conteúdo principal

Devolução enviada de Pix Webhook

info

📘 Para saber mais sobre webhooks em nossa API, siga o link abaixo:

Sobre Webhooks

Quando um pagamento Pix é creditado em sua conta e um reembolso é emitido, a melhor maneira de receber atualizações sobre possíveis erros é por meio do webhook PIX_REFUND_PAYMENT_UPDATED. Se ocorrer um erro durante o processo de reembolso, o status da transação será atualizado e um webhook PIX_REFUND_PAYMENT_UPDATED será acionado.

atenção

Note que este webhook é específico para erros relacionados a reembolsos Pix. Para pagamentos Pix bem-sucedidos — incluindo reembolsos Pix enviados — use PIX_PAYMENT_UPDATED é usado.

Esta é a maneira mais simples de configurar um webhook PIX_REFUND_PAYMENT_UPDATED:

Headers

NomeDescrição
x-delbank-api-keyObrigatório. Chave de API

Corpo da requisição

{
"eventType": "PIX_REFUND_PAYMENT_UPDATED",
"url": "https://example.com.br/webhooks/v1/pixrefundsent", // Add your own URL here
"authorization": "NONE,
"authorizationScheme": "NONE"
}

Aqui está um exemplo de um webhook de um erro em um reembolso Pix enviado:

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

Aqui estão os atributos que são passados ​​pelo webhook PIX_REFUND_PAYMENT_UPDATED:

NameDescription
statusO status da transação de reembolso PIX.
errorObjeto contendo informações sobre o erro
error.codeCódigo interno atribuído ao erro
error.descriptionDescrição do que causou o erro
eventTypeO tipo de evento que acionou o webhook (ex.: "PIX_REFUND_PAYMENT_EFFECTIVE").
operationTypeO tipo de operação que está sendo realizada.
endToEndIdO identificador único para a transação de reembolso PIX.
originalEndToEndIdO identificador único para a transação PIX original que está sendo reembolsada.
idempotencyKeyUma chave única para garantir a idempotência do processamento do evento.
correlationIdO id correlação da transação
amountO valor monetário da transação de reembolso PIX.
createdAtO timestamp indicando quando a transação de reembolso PIX foi criada.
descriptionUma descrição textual explicando o motivo do reembolso (ex.: "Pedido reembolso").
payerUm objeto contendo informações sobre o pagador da transação de reembolso PIX.
payer.numberO número da conta do pagador.
payer.branchO número da agência da conta do pagador.
payer.typeO tipo da conta do pagador (ex.: "CURRENT").
payer.participantUm objeto contendo informações sobre a instituição financeira do pagador.
payer.participant.ispbO código ISPB da instituição financeira do pagador (ex.: "38224857").
payer.holderUm objeto contendo informações sobre o titular da conta do pagador.
payer.holder.nameO nome do titular da conta do pagador (ex.: "EMPRESA LTDA").
payer.holder.documentO documento do titular da conta do pagador (ex.: "94478450000138").
payer.holder.typeO tipo do titular da conta do pagador (ex.: "LEGAL").
beneficiaryUm objeto contendo informações sobre o beneficiário da transação de reembolso PIX.
beneficiary.numberO número da conta do beneficiário.
beneficiary.branchO número da agência da conta do beneficiário.
beneficiary.typeO tipo da conta do beneficiário (ex.: "PAYMENT").
beneficiary.participantUm objeto contendo informações sobre a instituição financeira do beneficiário.
beneficiary.participant.ispbO código ISPB da instituição financeira do beneficiário (ex.: "1111111111").
beneficiary.holderUm objeto contendo informações sobre o titular da conta do beneficiário.
beneficiary.holder.documentO documento do titular da conta do beneficiário (ex.: parcialmente mascarado).
beneficiary.holder.typeO tipo do titular da conta do beneficiário (ex.: "NATURAL" ou "LEGAL").
payeeUm objeto contendo informações sobre o recebedor da transação de reembolso PIX.
payee.numberO número da conta do recebedor.
payee.branchO número da agência da conta do recebedor.
payee.typeO tipo da conta do recebedor (ex.: "PAYMENT").
payee.participantUm objeto contendo informações sobre a instituição financeira do recebedor.
payee.participant.ispbO código ISPB da instituição financeira do recebedor (ex.: "1111111111").
payee.holderUm objeto contendo informações sobre o titular da conta do recebedor.
payee.holder.documentO documento do titular da conta do recebedor (ex.: parcialmente mascarado).
payee.holder.typeO tipo do titular da conta do recebedor (ex.: "NATURAL" ou "LEGAL").