Skip to main content
POST
Open a MED refund request

Authorizations

Authorization
string
header
required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency
string
required

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.

Example:

"med-refund-2024-0001"

Body

application/json
endToEndId
string
required

EndToEndId of the contested payment (or pacs.004 id for a cancellation motivo).

Example:

"E1234567820240101000000000000001"

motivo
integer<int64>
required
deprecated

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).

Example:

1

valorDevolucao
integer<int64>
required
deprecated

Deprecated: send refundAmount instead. Both names are accepted; sending both with different values is refused 400 PIX-0148. Requested refund amount, in centavos.

Example:

25000

details
string

Free-text detail; required when motivo=0 (Falha Operacional). Replaces the deprecated detalhes, which is still accepted.

Example:

"Suspected scam."

detalhes
string
deprecated

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).

Example:

"Suspected scam."

ispb
string

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.

Pattern: ^[0-9]{8}$
Example:

"12345678"

reason
integer<int64>

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.

Example:

1

refundAmount
integer<int64>

Requested refund amount, in centavos. Required: send it under this name or under the deprecated valorDevolucao; neither is refused 400 PIX-0061.

Example:

25000

Response

Accepted

breached
boolean
required

True when the analysis deadline has been reached or passed (computed at read time); false when no deadline is set.

Example:

false

contestedIspb
string
required

ISPB of the contested PSP.

Example:

"87654321"

createdAt
string
required

JDPI creation timestamp (RFC 3339 UTC).

Example:

"2024-01-01T12:00:00.000Z"

dtHrCriacao
string
required
deprecated

Deprecated: read createdAt, which carries the same value. JDPI creation timestamp (RFC 3339 UTC).

Example:

"2024-01-01T12:00:00.000Z"

dtHrUltModificacao
string
required
deprecated

Deprecated: read updatedAt, which carries the same value. JDPI last-modification timestamp (RFC 3339 UTC) — the poll watermark.

Example:

"2024-01-01T12:05:00.000Z"

endToEndId
string
required

EndToEndId of the contested payment or devolucao.

Example:

"E1234567820240101000000000000001"

idSolDevolucao
string
required
deprecated

Deprecated: read refundRequestId, which carries the same value. Refund-request GUID (the natural key).

Example:

"d4e5f6a7-b8c9-0123-def4-56789012345a"

ispbContestado
string
required
deprecated

Deprecated: read contestedIspb, which carries the same value. ISPB of the contested PSP.

Example:

"87654321"

ispbSolicitante
string
required
deprecated

Deprecated: read requesterIspb, which carries the same value. ISPB of the requesting PSP.

Example:

"12345678"

motivo
integer<int64>
required
deprecated

Deprecated: read reason, which carries the same value. Refund motivo code (0=Falha Operacional, 1=Fraude, 3=Pix Automatico).

Example:

1

motivoDescription
string
required
deprecated

Deprecated: read reasonDescription, which carries the same value. Human-readable refund motivo label.

Example:

"Fraude"

reason
integer<int64>
required

Refund motivo code (0=Falha Operacional, 1=Fraude, 3=Pix Automatico).

Example:

1

reasonDescription
string
required

Human-readable refund motivo label.

Example:

"Fraude"

refundAmount
integer<int64>
required

Requested refund amount, in centavos.

Example:

25000

refundRequestId
string
required

Refund-request GUID (the natural key).

Example:

"d4e5f6a7-b8c9-0123-def4-56789012345a"

requesterIspb
string
required

ISPB of the requesting PSP.

Example:

"12345678"

status
integer<int64>
required

stSolDevolucao lifecycle code (0=Aberta, 1=Cancelada, 2=Analisada).

Example:

0

statusDescription
string
required

Human-readable stSolDevolucao label.

Example:

"Aberta"

updatedAt
string
required

JDPI last-modification timestamp (RFC 3339 UTC) — the poll watermark.

Example:

"2024-01-01T12:05:00.000Z"

valorDevolucao
integer<int64>
required
deprecated

Deprecated: read refundAmount, which carries the same value. Requested refund amount, in centavos.

Example:

25000

analysisDeadline
string

Contestado-side analysis deadline (RFC 3339 UTC; contract §5, 6h Fraude / 48h otherwise); null for filer-side and terminal requests.

Example:

"2024-01-01T18:00:00.000Z"

analysisDetails
string

Analysis detail.

Example:

"Insufficient balance."

analysisResult
integer<int64>

Refund analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada); null until analysed.

Example:

0

analysisResultDescription
string

Human-readable refund analysis-result label.

Example:

"Aceita Totalmente"

details
string

Free-text detail.

Example:

"Operational failure."

detalhes
string
deprecated

Deprecated: read details, which carries the same value. Free-text detail.

Example:

"Operational failure."

detalhesAnalise
string
deprecated

Deprecated: read analysisDetails, which carries the same value. Analysis detail.

Example:

"Insufficient balance."

dtHrRegistro
string
deprecated

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.

Example:

"2021-08-06T10:33:08.241Z"

endToEndIdDevolucao
string
deprecated

Deprecated: read refundEndToEndId, which carries the same value. pacs.004/pacs.008 devolucao reference, recorded at analysis.

Example:

"D1234567820240101000000000000099"

idRecValores
string
deprecated

Deprecated: read recoveryId, which carries the same value. Value-recovery GUID, when from a recovery.

Example:

"b2c3d4e5-f6a7-8901-bcde-f23456789012"

idRelatoInfracao
string
deprecated

Deprecated: read infractionId, which carries the same value. Linked infraction GUID, when fraud.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

infractionId
string

Linked infraction GUID, when fraud.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

motivoRejeicao
integer<int64>
deprecated

Deprecated: read rejectionReason, which carries the same value. Rejection reason (0,1,3,4); present only when the analysis rejected the request.

Example:

0

motivoRejeicaoDescription
string
deprecated

Deprecated: read rejectionReasonDescription, which carries the same value. Human-readable rejection-reason label.

Example:

"Falta de saldo"

recoveryId
string

Value-recovery GUID, when from a recovery.

Example:

"b2c3d4e5-f6a7-8901-bcde-f23456789012"

refundEndToEndId
string

pacs.004/pacs.008 devolucao reference, recorded at analysis.

Example:

"D1234567820240101000000000000099"

refundedAmount
integer<int64>

Amount actually refunded, in centavos; null when absent.

Example:

25000

registeredAt
string

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.

Example:

"2021-08-06T10:33:08.241Z"

rejectionReason
integer<int64>

Rejection reason (0,1,3,4); present only when the analysis rejected the request.

Example:

0

rejectionReasonDescription
string

Human-readable rejection-reason label.

Example:

"Falta de saldo"

resultadoAnalise
integer<int64>
deprecated

Deprecated: read analysisResult, which carries the same value. Refund analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada); null until analysed.

Example:

0

resultadoAnaliseDescription
string
deprecated

Deprecated: read analysisResultDescription, which carries the same value. Human-readable refund analysis-result label.

Example:

"Aceita Totalmente"

valorDevolvido
integer<int64>
deprecated

Deprecated: read refundedAmount, which carries the same value. Amount actually refunded, in centavos; null when absent.

Example:

25000