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

Path Parameters

idSolDevolucao
string
required

The refund-request GUID.

Example:

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

Query Parameters

ispb
string

The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it.

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

"12345678"

indirectId
string<uuid>

The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it.

Example:

"3f2504e0-4f89-41d3-9a0c-0305e82c3301"

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"

endToEndId
string
required

EndToEndId of the contested payment or refund.

Example:

"E1234567820240101000000000000001"

reason
integer<int64>
required

Refund reason code (0=operational failure, 1=fraud, 3=Pix Automatico).

Example:

1

reasonDescription
string
required

Human-readable refund reason 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=open, 1=cancelled, 2=analyzed).

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"

analysisDeadline
string

Contested-side analysis deadline (RFC 3339 UTC; contract §5, 6h for fraud / 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."

infractionId
string

Linked infraction GUID, when fraud.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

recoveryId
string

Value-recovery GUID, when from a recovery.

Example:

"b2c3d4e5-f6a7-8901-bcde-f23456789012"

refundEndToEndId
string

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

Example:

"D1234567820240101000000000000099"

refundedAmount
integer<int64>

Amount actually refunded, in centavos; null when absent.

Example:

25000

registeredAt
string

When the request was REGISTERED in the JDPI base (raw JDPI instant), distinct from createdAt (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"