Documentação
Status PageSuporte
Start typing to search…
  1. Pix Indireto
  2. MED 2.0

Fechar uma Recuperação de valores

Recebendo uma Recuperação de valores.


Quando você for a empresa da ponta recebedora de uma solicitação de recuperação de valores, receberá um webhook de evento: pix-infraction e nele conterá o campo fundsRecoveryId que é o ID da recuperação de valores que recebeu e indicando ser fluxo do MED 2.0. Como prazo são 7 dias corridos para realizar a análise e responder aceitando ou rejeitando essa solicitação mediante a uma fraude.

Assim que receber uma solicitação de recuperação de valores, deverá bloquear o saldo contestado cautelarmente da conta do usuário, para que esse saldo fique bloqueado enquanto a análise seja feita em até 7 dias. Caso constate que não se trata de uma fraude, deve debloquear o saldo, seja ele total ou parcial, caso contrário o saldo continua bloqueado e aguardando a solicitação de devolução enviada pela outra IF. Mais abaixo haverá detalhes de como responder uma análise de solicitação de recuperação de valores.

📘

Observação: este fluxo inteiro (endpoints e webhooks) será o mesmo para as notificações do MED 1.0 (infractions) quanto do MED 2.0 (recuperação de valores).


Exemplo de webhook que será enviado

Entity: pix-infraction
Status ACKNOWLEDGED

{
	"lastUpdateTimestamp": "0001-01-01T00:00:00",
	"body": {
		"infractionType": "REFUND_REQUEST",
		"creationTime": "2026-03-03T02:19:39.545+00:00",
		"reportDetails": "Notificamos que a Conta de destino pode estar associada a atividades fraudulentas. Por favor, confirme se há saldo disponível para que possamos proceder com a Solicitação de Devolução.",
		"responseTime": "0001-01-01T00:00:00",
		"contactCreator": {
			"contactEmail": "[email protected]",
			"contactPhone": "+55110000000"
		},
		"endToEndId": "E0856170120260302220479BDNRKR",
		"reportedBy": "DEBITED_PARTICIPANT",
		"infractionData": {
			"infractingAccountData": {
				"branch": 0
			},
			"debitedParticipant": "12345678",
			"reportedBy": "DEBITED_PARTICIPANT",
			"transactionDate": "0001-01-01T00:00:00",
			"creditedParticipant": "87654321"
		},
		"transactionId": "E0856170120260302220479BDNRK",
		"creditedParticipant": "87654321",
    "situationType": "SCAM",
		"fundsRecoveryId": "4464ad02-e0c0-4fb0-ad97-fca2b7841a83",
		"id": "faa2c47e-b5e8-4764-89cf-7dd93bf88",
		"debitedParticipant": "12345678",
		"lastModified": "2026-03-03T02:19:56.94+00:00",
		"status": "ACKNOWLEDGED"
	},
	"entity": "InfractionReport",
	"transactionId": 202603020000831840,
	"createTimestamp": "0001-01-01T00:00:00",
	"status": "ACKNOWLEDGED"
}


Rejeitando uma recuperação de valores como fraude

O próximo passo será responder a infração se será aceita ou recusada.

Caso a análise seja por rejeitar (DISAGREED) e entendendo que não se trata de uma fraude, deverá responder via API informando o id da infração que será recebido via webhook de evento pix-infraction.

Fechar/responder uma recuperação de valores

Post: https://sandbox.openfinance.celcoin.dev/pix-indirect/v1/infraction/{infratcionReportId}/close

curl --request POST \
     --url https://sandbox.openfinance.celcoin.dev/pix-indirect/v1/infraction/infratcionReportId/close \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "analysisResult": "DISAGREED",
  "analysisDetails": "Fraude não identificada",
  "fraudType": "APPLICATION_FRAUD"
}
'

Response de sucesso 200

{
  "status": "CLOSED",
  "creditedParticipant": "99999011",
  "debitedParticipant": "13935893",
  "infractionType": "APPLICATION_FRAUD",
  "reportedBy": "DEBITED_PARTICIPANT",
  "lastModified": "2023-05-22T14:02:00.426Z",
  "creationTime": "2023-05-22T14:02:00.426Z",
  "responseTime": "2023-05-22T14:02:00.426Z",
  "reportDetails": "Transação feita através de QR Code falso em boleto",
  "analysisResult": "DISAGREED",
  "correlationId": "A20210825095209b98f156a05d47f579",
  "analysisDetails": "Fraude não identificada",
  "id": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
  "endToEndId": "E3030629420200808185300887639654"
}

Após responder o fechamento da recuperação de valores, será enviado webhook informando que foi fechado.


Exemplo de webhook status CLOSED

entity: pix-infraction

{
    "lastUpdateTimestamp": "0001-01-01T00:00:00",
    "webhookId": "infraction-CLOSED-9eedec74-dcb5-42e3-b9b4-55536f589334",
    "body": {
        "analysisDetails": "Informamos que não há saldo disponível na conta, e o vínculo com o cliente foi encerrado.",
        "infractionType": "REFUND_REQUEST",
        "creationTime": "2026-03-02T12:57:36.99+00:00",
        "reportDetails": "Encaminhamos notificacao de infracao por motivo de fraude da transacao contestada pelo cliente.",
        "responseTime": "0001-01-01T00:00:00",
        "analysisResult": "DISAGREED",
        "contactCreator": {
            "contactEmail": "[email protected]",
            "contactPhone": "+5511000000"
        },
        "endToEndId": "E60746948202602091451C0572800000",
        "reportedBy": "DEBITED_PARTICIPANT",
        "infractionData": {
            "infractingAccountData": {
                "branch": 0
            },
            "debitedParticipant": "12345678",
            "reportedBy": "DEBITED_PARTICIPANT",
            "transactionDate": "0001-01-01T00:00:00",
            "creditedParticipant": "87654321"
        },
        "transactionId": "E60746948202602091451C05728E",
        "creditedParticipant": "87654321",
      	"situationType": "FRAUDULENT_ACCESS",
				"fundsRecoveryId": "4464ad02-e0c0-4fb0-ad97-fca2b7841a83",
        "id": "9eedec74-dcb5-42e3-b9b4-55536f589334",
        "debitedParticipant": "12345678",
        "lastModified": "2026-03-02T13:41:38.644+00:00",
        "status": "CLOSED"
    },
    "entity": "InfractionReport",
    "transactionId": 4986399242,
    "createTimestamp": "0001-01-01T00:00:00",
    "status": "CLOSED"
}


Aceitando a recuperação de valores como fraude

Quando a análise de uma recuperação de valor for aceita como fraude, o fluxo continua o mesmo, sendo necessário responder via API com o analysisResult =AGREED.

Fechar/responder uma recuperação de valores

Post: https://sandbox.openfinance.celcoin.dev/pix-indirect/v1/infraction/{infratcionReportId}/close

curl --request POST \
     --url https://sandbox.openfinance.celcoin.dev/pix-indirect/v1/infraction/infratcionReportId/close \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "analysisResult": "AGREED",
  "analysisDetails": "Após analise, realizamos o bloqueio definitivo do cadastro porem não possui saldo para devolução",
  "fraudType": "APPLICATION_FRAUD"
}
'

Response de sucesso 200


{
  "status": "OPEN",
  "creditedParticipant": "99999011",
  "debitedParticipant": "13935893",
  "infractionType": "FRAUD",
  "reportedBy": "DEBITED_PARTICIPANT",
  "lastModified": "2023-05-22T14:02:00.426Z",
  "creationTime": "2023-05-22T14:02:00.426Z",
  "responseTime": "2023-05-22T14:02:00.426Z",
  "reportDetails": "Transação feita através de QR Code falso em boleto",
  "analysisResult": "AGREED",
  "correlationId": "A20210825095209b98f156a05d47f579",
  "analysisDetails": "Após analise, realizamos o bloqueio definitivo do cadastro porem não possui saldo para devolução",
  "id": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
  "endToEndId": "E3030629420200808185300887639654"
}

Após responder o fechamento da recuperação de valores, será enviado webhook informando que foi fechado.

Exemplo de webhook status CLOSED

entity: pix-infraction


{
    "lastUpdateTimestamp": "0001-01-01T00:00:00",
    "webhookId": "infraction-CLOSED-9eedec74-dcb5-42e3-b9b4-55536f589334",
    "body": {
        "analysisDetails": "Informamos que não há saldo disponível na conta, e o vínculo com o cliente foi encerrado.",
        "infractionType": "REFUND_REQUEST",
        "creationTime": "2026-03-02T12:57:36.99+00:00",
        "reportDetails": "Encaminhamos notificacao de infracao por motivo de fraude da transacao contestada pelo cliente.",
        "responseTime": "0001-01-01T00:00:00",
        "analysisResult": "AGRRED",
        "contactCreator": {
            "contactEmail": "[email protected]",
            "contactPhone": "+5511000000"
        },
        "endToEndId": "E60746948202602091451C0572800000",
        "reportedBy": "DEBITED_PARTICIPANT",
        "infractionData": {
            "infractingAccountData": {
                "branch": 0
            },
            "debitedParticipant": "12345678",
            "reportedBy": "DEBITED_PARTICIPANT",
            "transactionDate": "0001-01-01T00:00:00",
            "creditedParticipant": "87654321"
        },
        "transactionId": "E60746948202602091451C05728E",
        "creditedParticipant": "87654321",
      	"situationType": "FRAUDULENT_ACCESS",
				"fundsRecoveryId": "4464ad02-e0c0-4fb0-ad97-fca2b7841a83",
        "id": "9eedec74-dcb5-42e3-b9b4-55536f589334",
        "debitedParticipant": "12345678",
        "lastModified": "2026-03-02T13:41:38.644+00:00",
        "status": "CLOSED"
    },
    "entity": "InfractionReport",
    "transactionId": 4986399242,
    "createTimestamp": "0001-01-01T00:00:00",
    "status": "CLOSED"
}


👍

Para casos onde a infração ou recuperação de valores foi aceita, seguir a documentação de "Fechar devolução em recuperação de valores".


Infração cancelada pela IF contestante.


Quando a IF que abriu a solicitação de recuperação de valores cancelar essa solicitação, será enviado um webhook informando esse cancelamento. Nesse cenário não é necessário tomar nenhuma ação, o próprio cancelamento encerrará o fluxo.

Exemplo de webhook CANCELLED

entity: pix-infraction


{
	"lastUpdateTimestamp": "0001-01-01T00:00:00",
	"webhookId": "infraction-CANCELLED-631302f0-9c17-4ba8-865a-a74cae6d49cf",
	"body": {
		"infractionType": "REFUND_REQUEST",
		"creationTime": "2026-02-27T23:09:40.332+00:00",
		"reportDetails": "Acreditei que estava fazendo um investimento",
		"responseTime": "0001-01-01T00:00:00",
		"contactCreator": {
			"contactEmail": "[email protected]",
			"contactPhone": "+5511000000"
		},
		"endToEndId": "E60701190202602272302DY59HS",
		"reportedBy": "DEBITED_PARTICIPANT",
		"infractionData": {
			"infractingAccountData": {
				"branch": 0
			},
			"debitedParticipant": "12345678",
			"reportedBy": "DEBITED_PARTICIPANT",
			"transactionDate": "0001-01-01T00:00:00",
			"creditedParticipant": "87654321"
		},
		"transactionId": "E60701190202602272302DY59HSIW8TU",
		"creditedParticipant": "87654321",
		"situationType": "SCAM",
    "id": "631302f0-9c17-4ba8-865a-a74cae6d49cf",
		"fundsRecoveryId": "4464ad02-e0c0-4fb0-ad97-fca2b7841a83",
		"debitedParticipant": "12345678",
		"lastModified": "2026-03-02T12:10:00.839+00:00",
		"status": "CANCELLED"
	},
	"entity": "InfractionReport",
	"transactionId": 2026022700008691,
	"createTimestamp": "0001-01-01T00:00:00",
	"status": "CANCELLED"
}


Tabela de apoio para fechar/responder recuperação de valores


Campo

Descrição

Tipo do Campo

infractionReportId

ID da Infração a ser consultada

string

analysisResult

Esse campo deve ser preenchido como:

  • AGREED, para aceitar a infração.
  • DISAGREED, para rejeitar a infração.

string

analysisDetails

Detalhes da análise da infração, que possam orientar o pagador dos próximos passos (exemplo: O valor da transação será estornado em até 5 dias úteis)

string

fraudType

Tipo da fraude:
APPLICATION_FRAUD MULE_ACCOUNT SCAMMER_ACCOUNT OTHER UNKNOWN

string



Updated about 7 hours ago