Open a MED refund request
Opens a refund request as the solicitante PSP (JDPI devolucao/incluir, contract 2.7). The requesting ISPB is derived from configuration. Persists the JDPI response entity and returns it.
Authorizations
JWT bearer token issued by the identity provider.
Headers
Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists.
"med-refund-2024-0001"
Body
- Option 1
- Option 2
- Option 3
- Option 4
EndToEndId of the contested payment (or pacs.004 id for a cancellation motivo).
"E1234567820240101000000000000001"
Deprecated: send reason instead. Both names are accepted; sending both with different values is refused 400 PIX-0148. Refund motivo (0=Falha Operacional, 1=Fraude, 3=Pix Automatico).
1
Deprecated: send refundAmount instead. Both names are accepted; sending both with different values is refused 400 PIX-0148. Requested refund amount, in centavos.
25000
Free-text detail; required when motivo=0 (Falha Operacional). Replaces the deprecated detalhes, which is still accepted.
"Suspected scam."
Deprecated: send details instead. Both names are accepted; sending both with different values is refused 400 PIX-0148. Free-text detail; required when motivo=0 (Falha Operacional).
"Suspected scam."
The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the JDPI channel the call goes out on, so a MED write made under the wrong one reaches a JD that has never heard of this institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061.
^[0-9]{8}$"12345678"
Refund motivo (0=Falha Operacional, 1=Fraude, 3=Pix Automatico). Required: send it under this name or under the deprecated motivo; neither is refused 400 PIX-0061.
1
Requested refund amount, in centavos. Required: send it under this name or under the deprecated valorDevolucao; neither is refused 400 PIX-0061.
25000
Response
Accepted
True when the analysis deadline has been reached or passed (computed at read time); false when no deadline is set.
false
ISPB of the contested PSP.
"87654321"
JDPI creation timestamp (RFC 3339 UTC).
"2024-01-01T12:00:00.000Z"
Deprecated: read createdAt, which carries the same value. JDPI creation timestamp (RFC 3339 UTC).
"2024-01-01T12:00:00.000Z"
Deprecated: read updatedAt, which carries the same value. JDPI last-modification timestamp (RFC 3339 UTC) — the poll watermark.
"2024-01-01T12:05:00.000Z"
EndToEndId of the contested payment or devolucao.
"E1234567820240101000000000000001"
Deprecated: read refundRequestId, which carries the same value. Refund-request GUID (the natural key).
"d4e5f6a7-b8c9-0123-def4-56789012345a"
Deprecated: read contestedIspb, which carries the same value. ISPB of the contested PSP.
"87654321"
Deprecated: read requesterIspb, which carries the same value. ISPB of the requesting PSP.
"12345678"
Deprecated: read reason, which carries the same value. Refund motivo code (0=Falha Operacional, 1=Fraude, 3=Pix Automatico).
1
Deprecated: read reasonDescription, which carries the same value. Human-readable refund motivo label.
"Fraude"
Refund motivo code (0=Falha Operacional, 1=Fraude, 3=Pix Automatico).
1
Human-readable refund motivo label.
"Fraude"
Requested refund amount, in centavos.
25000
Refund-request GUID (the natural key).
"d4e5f6a7-b8c9-0123-def4-56789012345a"
ISPB of the requesting PSP.
"12345678"
stSolDevolucao lifecycle code (0=Aberta, 1=Cancelada, 2=Analisada).
0
Human-readable stSolDevolucao label.
"Aberta"
JDPI last-modification timestamp (RFC 3339 UTC) — the poll watermark.
"2024-01-01T12:05:00.000Z"
Deprecated: read refundAmount, which carries the same value. Requested refund amount, in centavos.
25000
Contestado-side analysis deadline (RFC 3339 UTC; contract §5, 6h Fraude / 48h otherwise); null for filer-side and terminal requests.
"2024-01-01T18:00:00.000Z"
Analysis detail.
"Insufficient balance."
Refund analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada); null until analysed.
0
Human-readable refund analysis-result label.
"Aceita Totalmente"
Free-text detail.
"Operational failure."
Deprecated: read details, which carries the same value. Free-text detail.
"Operational failure."
Deprecated: read analysisDetails, which carries the same value. Analysis detail.
"Insufficient balance."
Deprecated: read registeredAt, which carries the same value. dtHrRegistro — when the request was REGISTERED in the JDPI base (raw JDPI instant), distinct from dtHrCriacao (the DICT creation instant). Returned by the §8.2.26 JDPI-base read only.
"2021-08-06T10:33:08.241Z"
Deprecated: read refundEndToEndId, which carries the same value. pacs.004/pacs.008 devolucao reference, recorded at analysis.
"D1234567820240101000000000000099"
Deprecated: read recoveryId, which carries the same value. Value-recovery GUID, when from a recovery.
"b2c3d4e5-f6a7-8901-bcde-f23456789012"
Deprecated: read infractionId, which carries the same value. Linked infraction GUID, when fraud.
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Linked infraction GUID, when fraud.
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Deprecated: read rejectionReason, which carries the same value. Rejection reason (0,1,3,4); present only when the analysis rejected the request.
0
Deprecated: read rejectionReasonDescription, which carries the same value. Human-readable rejection-reason label.
"Falta de saldo"
Value-recovery GUID, when from a recovery.
"b2c3d4e5-f6a7-8901-bcde-f23456789012"
pacs.004/pacs.008 devolucao reference, recorded at analysis.
"D1234567820240101000000000000099"
Amount actually refunded, in centavos; null when absent.
25000
dtHrRegistro — when the request was REGISTERED in the JDPI base (raw JDPI instant), distinct from dtHrCriacao (the DICT creation instant). Returned by the §8.2.26 JDPI-base read only.
"2021-08-06T10:33:08.241Z"
Rejection reason (0,1,3,4); present only when the analysis rejected the request.
0
Human-readable rejection-reason label.
"Falta de saldo"
Deprecated: read analysisResult, which carries the same value. Refund analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada); null until analysed.
0
Deprecated: read analysisResultDescription, which carries the same value. Human-readable refund analysis-result label.
"Aceita Totalmente"
Deprecated: read refundedAmount, which carries the same value. Amount actually refunded, in centavos; null when absent.
25000

