Fechar devolução em recuperação de valores
Solicitação de devolução em recuperação de valores
Quando é aceito uma recuperação de valores (AGREED), será aberto pela IF da vítima de fraude uma solicitação de devolução em recuperação de valores em até 6 horas.
Você, cliente Celcoin, receberá essa solicitação de devolução via webhook de pix-med-refund, nele conterá os dados para prosseguir com a devolução.
O objeto de refundaccount trará os dados para devolução, o campo monitorAccount indica os casos onde o Bacen/DICT estabelece que independente de ter saldo ou não, a instituição recebedora deverá continuar monitorando esta conta para possíveis cash in.
O campo fundsrecoveryid, que é o identificador da recuperação de valores, além de outros campos como o refundamount com o valor indicado para devolução.
Primeiramente, será recebido o webhook com o status "Open", que indica que a solicitação está aberto e é possível realizar a devolução dos valores.
Exemplo de recebimento de solicitação de devolução status OPEN webhook pix-med-refund:
{
"lastUpdateTimestamp": "2026-03-02T10:23:51.987",
"webhookId": "refund-OPEN-60807e2d-e82c-45b2-b812-9f4a3cb7ef6f",
"clientRequestId": "1646",
"clientCode": "",
"body": {
"creationTime": "03/02/2026 10:23:51",
"refundReason": "FRAUD",
"responseTime": "03/02/2026 10:23:51",
"refundDetails": "Detalhes sobre o MED",
"transactionId": "E3344900720260302130796vwZ",
"requestingParticipant": "12345678",
"monitorAccount": true,
"contestedParticipant": "87456321",
"infractionReportId": "09c29508-3600-4895-b091-2924148c7ba7",
"fundsRecoveryId": "672e68fe-e9fe-401c-9a30-d89ada434828",
"id": "60807e2d-e82c-45b2-b812-9f4a3cb7ef6f",
"lastModified": "03/02/2026 10:23:51",
"originalEndToEndId": "E3344900720260302130796vwZpna",
"refundAmount": "20.50",
"refundaccount": {
"taxid": "22222222222",
"bank": "123456",
"branch": "1234",
"accounttype": "CACC",
"account": "12345678"
},
"status": "OPEN"
},
"entity": "DictRefund",
"transactionId": 2026030200000000,
"createTimestamp": "2026-03-02T10:23:51.987",
"status": "OPEN"
}Se no webhook o campo refundaccount vier preenchido com dados da conta, indica que seu usuário é de contas subsequentes da fraude e deverá ser feito uma transação para os dados da conta contido no campo refundaccount, onde o titular da conta que fará a devolução deverá ser o participante indireto e não o titular da conta do usuário. Essa regra é estipulada pelo Banco Central.
Caso o campo "refundaccount" não venha preenchido, basta fazer a devolução da transação recebida.
Fechando uma solicitação de devolução quando seu usuário é a transação raiz (campo "refundaccount" não preenchido)
Após o recebimento do webhook pix-med-refund, você poderá fechar a solicitação de devolução recebida via API, devolvendo o valor parcial, valor total ou respondendo que não há saldo. Para fechar a devolução, deverá já ter realizado a transação de devolução e preencher na API o transactionId dessa transação de devolução, só assim a solicitação de devolução será fechada com sucesso.
Para realizar a devolução, você deverá efetivar uma chamada pelo fluxo normal de pix-reversal-out, informando o motivo FR01, para devoluções por suspeita de fraude e utilizar o campo "originalEndToEndId" recebido via webhook pix-med-refund. Para mais detalhes, acesse a documentação de devolução de recebimentos pix.
Após a devolução ter sido efetivada, você poderá Fechar/responder a solicitação de devolução
Post/ https://sandbox.openfinance.celcoin.dev/pix-indirect/v1/med/refund/{refundId}/close
curl --request POST \
--url https://sandbox.openfinance.celcoin.dev/pix-indirect/v1/med/refund/refundId/close \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"transactionId": 745856954,
"refundRejectionReason": null,
"refundAnalysisDetails": "Saldo parcial bloqueado na conta do fraudador.",
"refundAnalysisResult": "PARCIALlY_ACCEPTED",
"refundAmount": 50.14
}
'Response de sucesso 200
{
"transactionId": 745856954,
"status": "CLOSED",
"refundAmount": 50.14,
"creationTime": "2021-10-15T16:59:06.389Z",
"lastModified": "2021-10-15T16:59:06.389Z",
"contestedParticipant": "Banco do Brasil SA",
"refundReason": "FRAUD",
"refundDetails": "Algum texto explicativo de motivo da abertura do pedido de devolução aqui",
"requestingParticipant": "Celcoin Pagamentos SA",
"analysisResult": "PARCIALlY_ACCEPTED",
"endToEndId": "E30306294202110041316KL5BCD0OHEM",
"infractionReportId": "cfdff46e-5d58-45b8-b7aa-591a65f7760d",
"refundId": "cfdff46e-5d58-45b8-b7aa-591a65f7760d",
"analysisDetails": "Algum texto explicativo de detalhes de análise do pedido de devolução aqui"
}Deverá ser recebido webhook indicando que a solicitação de devolução foi encerrada.
Exemplo de webhook status CLOSED
entidade: pix-med-refund
{
"lastUpdateTimestamp": "2026-02-25T10:14:30.583",
"webhookId": "refund-CLOSED-180a0be9-43f5-4b3d-9516-4f5a6d608ba5",
"clientRequestId": "1679",
"clientCode": "0f388b73-5118-439d-b94d-5eebee594d",
"body": {
"creationTime": "02/24/2026 17:17:52",
"refundReason": "FRAUD",
"responseTime": "02/25/2026 10:14:30",
"refundDetails": "aceita",
"analysisResult": "PARCIALlY_ACCEPTED",
"transactionId": "E27970567202602190449zAAyUKHqfIS",
"requestingParticipant": "27970567",
"monitorAccount": false,
"contestedParticipant": "11351086",
"infractionReportId": "201ee953-49a0-4460-b318-f8e3e63e4b6b",
"id": "180a0be9-43f5-4b3d-9516-4f5a6d608ba5",
"lastModified": "02/25/2026 10:14:30",
"originalEndToEndId": "E27970567202602190449zAAyUKHqfIS",
"refundAmount": "30.14",
"status": "CLOSED",
"fundsrecoveryid": "7b70e88c-1346-49fb-a448-acb120e126c6",
"refundaccount": {
"taxid": "22222222222",
"bank": "123456",
"branch": "1234",
"accounttype": "CACC",
"account": "12345678"
}
},
"entity": "DictRefund",
"transactionId": 202602190000067170,
"createTimestamp": "2026-02-24T17:17:52.43",
"status": "CLOSED"
}Fechando uma solicitação de devolução quando seu usuário é de contas/camadas subsequentes
Se caso a o webhook pix-med-refund de status OPEN vier com o campo "refundaccount" preenchido com dados da conta, indicará que seu usuário é de conta subsequente da conta recebedor da transação raiz de fraude. Nesse caso, caso a devolução ocorrerá de uma outra forma, conforme estipula o Banco Central.
Deverá retirar o saldo bloqueado da conta do usuário fraudador e passar para uma conta de titularidade do Participante Indireto cliente Celcoin, e desta conta será feito um pix cash out novo com destino para conta da vitima da fraude. Esse fluxo é estipulado pelo Banco Central conforme o guia do MED 2.0.
Com o saldo já na conta de titularidade do participante Indireto cliente Celcoin, será feito uma nova transação de pix cash out com destino para os dados da conta que vieram no campo "refundaccount" via webhook, utilizando a API de payment preencherá o campo "creditParty" com os dados da "refundAccount" e o tipo "transactionType" com o valor "PAYMENT_REFUND".
Após o sucesso desse cash out será gerado um transactionId que será utilizado no request body para fechar a solicitação de devolução.
Fechar/responder a solicitação de devolução
curl --request POST \
--url https://sandbox.openfinance.celcoin.dev/pix-indirect/v1/med/refund/refundId/close \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"transactionId": 745856954,
"refundRejectionReason": null,
"refundAnalysisDetails": "Saldo parcial bloqueado na conta do fraudador.",
"refundAnalysisResult": "PARCIALlY_ACCEPTED",
"refundAmount": 50.14
}
'Response de sucesso 200
{
"transactionId": 745856954,
"status": "CLOSED",
"refundAmount": 50.14,
"creationTime": "2021-10-15T16:59:06.389Z",
"lastModified": "2021-10-15T16:59:06.389Z",
"contestedParticipant": "Banco do Brasil SA",
"refundReason": "FRAUD",
"refundDetails": "Algum texto explicativo de motivo da abertura do pedido de devolução aqui",
"requestingParticipant": "Celcoin Pagamentos SA",
"analysisResult": "PARCIALlY_ACCEPTED",
"endToEndId": "E30306294202110041316KL5BCD0OHEM",
"infractionReportId": "cfdff46e-5d58-45b8-b7aa-591a65f7760d",
"refundId": "cfdff46e-5d58-45b8-b7aa-591a65f7760d",
"analysisDetails": "Algum texto explicativo de detalhes de análise do pedido de devolução aqui"
}Deverá ser recebido webhook indicando que a solicitação de devolução foi encerrada.
Exemplo de webhook status CLOSED
entidade: pix-med-refund
{
"lastUpdateTimestamp": "2026-02-25T10:14:30.583",
"webhookId": "refund-CLOSED-180a0be9-43f5-4b3d-9516-4f5a6d608ba5",
"clientRequestId": "1679",
"clientCode": "0f388b73-5118-439d-b94d-5eebee594d",
"body": {
"creationTime": "02/24/2026 17:17:52",
"refundReason": "FRAUD",
"responseTime": "02/25/2026 10:14:30",
"refundDetails": "aceita",
"analysisResult": "PARCIALlY_ACCEPTED",
"transactionId": "E27970567202602190449zAAyUKHqfIS",
"requestingParticipant": "27970567",
"monitorAccount": false,
"contestedParticipant": "11351086",
"infractionReportId": "201ee953-49a0-4460-b318-f8e3e63e4b6b",
"id": "180a0be9-43f5-4b3d-9516-4f5a6d608ba5",
"lastModified": "02/25/2026 10:14:30",
"originalEndToEndId": "E27970567202602190449zAAyUKHqfIS",
"refundAmount": "30.14",
"status": "CLOSED",
"fundsrecoveryid": "7b70e88c-1346-49fb-a448-acb120e126c6",
"refundaccount": {
"taxid": "22222222222",
"bank": "123456",
"branch": "1234",
"accounttype": "CACC",
"account": "12345678"
}
},
"entity": "DictRefund",
"transactionId": 202602190000067170,
"createTimestamp": "2026-02-24T17:17:52.43",
"status": "CLOSED"
}Tabela de apoio para responder a solicitação de devolução
refundId | Identificador único da solicitação de devolução. | string | |
transactionId | Identificador da transação de devolução (completa ou parcial). Obrigatório em caso de aceite ("TOTALLY_ACCEPTED" ou "PARTIALLY_ACCEPTED") | int | |
refundRejectionReason | Razão da rejeição da solicitação de devolução. | string enum | |
refundAnalysisDetails | Detalhes da análise da requisição de devolução indicando a motivação do resultado. (O campo deve conter menos de 2000 caracteres). Obrigatório quando for "REJECTED" | string | |
refundAnalysisResult | Resultado da análise da requisição de devolução pelo contestado. | string enum | |
refundAmount | Valor que foi devolvido | double |
Updated about 5 hours ago