Receiving Refund Requests

Unlike infraction reports, refund requests, as long as they comply with certain guidelines, should, whenever possible, be closed with acceptance, unless the account is closed or has no balance. That said, the client will only receive webhooks for refund request status updates, as this is not something contestable, since the reasons for opening a refund request through MED are either due to an already accepted infraction report, or another participant opening one due to an operational failure.

Webhook for an incoming refund request

An incoming refund request is a refund opened by another bank, where the account holder is the target of the contested transaction.

Webhook request body

Webhook: incoming refund request

{
  "event_datetime": "2024-07-16T16:48:43Z",
  "key": "0dedf537-a75e-4945-be1d-5d278c623022",
  "data": {
    "refund_request_key": "9eb5f452-81fd-4f67-9f2a-49e14e53ef64",
    "infraction_report_key": "3541127e-cbc9-44f6-bb0e-3e346ddaefb4",
    "target_account_key": "6711e3cf-fdf4-41b4-88e8-0a31cb83b9f4",
    "refund_request_type": "fraud",
    "blocked_balance_status": "completelly_blocked",
    "pix_transfer_key": "957ef961-1824-47e6-90fd-f8b4775a1e1c",
    "end_to_end_id": "E12345678202404302308s188f18bJty",
    "requesting_participant": "18236120",
    "contested_participant": "32402502",
    "refund_request_details": null,
    "refund_payment_event": null,
    "requested_amount": 40,
    "refunded_amount": 0,
    "refund_request_status": "open",
    "analysis_result": null,
    "analysis_details": null,
    "reject_reason": null,
    "updated_at": "2024-07-16T19:48:43Z",
    "created_at": "2024-07-16T19:48:43Z"
  },
  "status": "open",
  "webhook_type": "incoming.internal_refund_request"
}

Field	Type	Description	Characters
event_datetime *	string	Date and time of transaction creation.	20
key *	string	Unique identification key for the event sending.	32
data *	string	Incoming refund request data object.	Object incoming_refund_request
status *	string	Refund status.	Enumerators refund_request_status

Enumerators refund_request_status

Enumerator	Description
open	Request received and pending analysis.
closed	Analysis completed and request closed.
cancelled	Request cancelled by the originator.

Object incoming_refund_request

Field	Type	Description	Characters
refund_request_key *	string	UUID4 identifier of the refund at Bacen.	32
infraction_report_key	string	UUID4 identifier of the related infraction at Bacen.	32
target_account_key *	string	Account key of the original transaction's target account.	32
refund_request_type *	string	Type of refund request.	Enumerators refund_request_type
pix_transfer_key *	string	Pix transfer key of the original transaction.	32
end_to_end_id *	string	end_to_end_id of the original transaction.	32
requesting_participant *	string	Participant that originated the transaction.	8
contested_participant *	string	Participant that received the transaction.	8
refund_request_details	string	Refund details sent by the other participant.	2000
refund_payment_event	string	Refund execution event.	Object refund_payment_event
requested_amount *	float	Amount requested in the refund.	2000
refunded_amount *	float	Total refunded amount.	2000
refund_request_status *	string	Refund status.	Enumerators refund_request_status
analysis_result	string	Analysis result. Decided by QI Tech.	Enumerators refund_request_analysis_result
analysis_details	string	Analysis result justification.	200
reject_reason	string	Request rejection reason.	Enumerators refund_request_reject_reason
blocked_balance_status *	string	Target account balance blocking status.	Enumerators blocked_balance_status
created_at *	string	Date and time of transaction modification.	20
updated_at *	string	Date and time of transaction creation.	20

Object refund_payment_event

Field	Type	Description	Characters
refund_end_to_end_id	string	end_to_end_id of the refund transaction.	32
refund_transfer_key	string	Pix transfer key of the refund transaction.	32
refund_amount	string	Amount of the refund transaction.
created_at	string	Date and time of transaction creation.	20

Enumerators refund_request_analysis_result

Enumerator	Description
totally_accepted	Refund executed for all requested amounts.
partially_accepted	Partial refund due to insufficient balance. Monitoring account for subsequent refunds.
rejected	Refund rejected and no resources were returned. If reason is insufficient balance, account will be monitored.

Enumerators refund_request_type

Enumerator	Description
fraud	Opened after accepting an infraction report.
operational_flaw	Opened without an infraction report, used to correct operational failures of participants.
refund_cancelled	Correction of a refund executed erroneously.

Enumerators blocked_balance_status

Enumerator	Description
no_balance	Customer account with no balance. Monitoring pending balance.
completelly_blocked	Resources equivalent to the transaction completely blocked.
partially_blocked	Resources equivalent to the transaction partially blocked. Monitoring balance.
settled	Infraction accepted, and refund request payment executed.
partially_settled	Infraction accepted, and refund request payment partially executed.
released	Resources released, either by infraction cancellation or disagreement closure.

Enumerators refund_request_reject_reason

Enumerator	Description
no_balance	Customer account with no balance. Monitoring pending balance.
account_closure	Customer relationship terminated. Impossible to execute refund.
other	Other reason, not applicable to those listed above.

info

Balance monitoring for an account with partial refund has a limit of 90 days after the original transaction occurs.

Webhook for an outgoing refund request

An outgoing refund request is a refund request opened by QI Tech, targeting another participant.

Webhook request body

Webhook: outgoing refund request

{
  "event_datetime": "2024-07-22T10:31:09Z",
  "key": "15d91f4b-a55c-41a6-9c46-2704253a1cf7",
  "data": {
    "refund_request_key": "5f98671e-9ec0-4ed7-95a9-061861243efc",
    "pix_transfer_key": "d04e0858-ea91-4dab-8089-a27d6cc68235",
    "source_account_key": "134ad635-ce80-4c8c-bca0-9dd3e8251317",
    "end_to_end_id": "E32402502202404302308s188f18bJty",
    "requested_amount": 78.5,
    "refund_request_status": "open",
    "infraction_report_key": "3b727ade-a736-473e-91a6-07b841253f55",
    "refund_request_type": "fraud",
    "refund_request_details": "Infraction aceita, favor realizar devolução de recursos.",
    "requesting_participant": "32402502",
    "contested_participant": "12345678",
    "analysis_result": null,
    "analysis_details": null,
    "reject_reason": null,
    "refund_payment_event": null,
    "updated_at": "2024-07-16T19:48:43Z",
    "created_at": "2024-07-16T19:48:43Z",
  },
  "status": "open",
  "webhook_type": "outgoing.internal_refund_request"
}

Field	Type	Description	Characters
event_datetime *	string	Date and time of transaction creation.	20
key *	enum	Unique identification key for the event sending.	32
data *	string	Outgoing infraction report data object.	Object outgoing_refund_request
status *	string	Refund status.	Enumerators refund_request_status

Object outgoing_refund_request

Field	Type	Description	Characters
refund_request_key *	string	UUID4 identifier of the refund at Bacen.	32
infraction_report_key	string	UUID4 identifier of the related infraction at Bacen.	32
source_account_key *	string	Account key of the transaction's source account.	32
refund_request_type *	string	Type of refund request.	Enumerators refund_request_type
pix_transfer_key *	string	Pix transfer key of the original transaction.	32
end_to_end_id *	string	end_to_end_id of the original transaction.	32
requesting_participant *	string	Participant that originated the transaction.	8
contested_participant *	string	Participant that received the transaction.	8
refund_request_details	string	Refund details sent by the other participant.	2000
refund_payment_event	string	Refund execution event.	Object refund_payment_event
requested_amount *	float	Amount requested in the refund.	2000
refund_request_status *	string	Refund status.	Enumerators refund_request_status
analysis_result	string	Analysis result. Decided by QI Tech.	Enumerators refund_request_analysis_result
analysis_details	string	Analysis result justification.	200
reject_reason	string	Request rejection reason.	Enumerators refund_request_reject_reason
created_at *	string	Date and time of transaction modification.	20
updated_at *	string	Date and time of transaction creation.	20