Skip to main content
POST
Analyze 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-analyze-2024-0001"

Path Parameters

idSolDevolucao
string
required

The refund-request GUID.

Example:

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

Body

application/json
resultadoAnalise
integer<int64>
required
deprecated

Deprecated: send analysisResult instead. Both names are accepted; sending both with different values is refused 400 PIX-0148. Analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada).

Example:

0

analysisDetails
string

Analysis detail; required when rejecting with motivoRejeicao=4. Replaces the deprecated detalhesAnalise, which is still accepted.

Example:

"Confirmed fraud."

analysisResult
integer<int64>

Analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada). Required: send it under this name or under the deprecated resultadoAnalise; neither is refused 400 PIX-0061.

Example:

0

detalhesAnalise
string
deprecated

Deprecated: send analysisDetails instead. Both names are accepted; sending both with different values is refused 400 PIX-0148. Analysis detail; required when rejecting with motivoRejeicao=4.

Example:

"Confirmed fraud."

endToEndIdDevolucao
string
deprecated

Deprecated: send refundEndToEndId instead. Both names are accepted; sending both with different values is refused 400 PIX-0148. pacs.004/008 devolucao id; required when resultadoAnalise is 0 or 1.

Example:

"D1234567820240101000000000000099"

motivoRejeicao
integer<int64>
deprecated

Deprecated: send rejectionReason instead. Both names are accepted; sending both with different values is refused 400 PIX-0148. Rejection reason (0,1,3,4); required when resultadoAnalise=2.

Example:

0

refundEndToEndId
string

pacs.004/008 devolucao id; required when resultadoAnalise is 0 or 1. Replaces the deprecated endToEndIdDevolucao, which is still accepted.

Example:

"D1234567820240101000000000000099"

refundedAmount
integer<int64>

Amount actually refunded, in centavos; required for a partial acceptance. Replaces the deprecated valorDevolvido, which is still accepted.

Example:

10000

rejectionReason
integer<int64>

Rejection reason (0,1,3,4); required when resultadoAnalise=2. Replaces the deprecated motivoRejeicao, which is still accepted.

Example:

0

valorDevolvido
integer<int64>
deprecated

Deprecated: send refundedAmount instead. Both names are accepted; sending both with different values is refused 400 PIX-0148. Amount actually refunded, in centavos; required for a partial acceptance.

Example:

10000

Response

OK

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