Amend a MED value recovery
Records a field-only update to a value recovery (JDPI recuperacao-valores/ PUT, contract 2.23 — Alterar). It NEVER changes status. The contract 2.23 invariants are validated before any JDPI call. An unknown id returns a coded 404. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the value recovery has to be over a root payment this deployment recorded for that indirect — the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.
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-amend-2024-0001"
Path Parameters
The value-recovery GUID.
"b2c3d4e5-f6a7-8901-bcde-f23456789012"
Query Parameters
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.
^[0-9]{8}$"12345678"
The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the value recovery has to be over a root payment this deployment recorded for that indirect - the rule GET /v1/med/recoveries/awaiting-return?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.
"3f2504e0-4f89-41d3-9a0c-0305e82c3301"
Body
New situation code (0..5).
4
New creator-contact email.
"ops@example.com"
New creator-contact phone.
"+5511999999999"
New free-text detail; required when situationType=4 (Outros).
"Updated detail."
Response
OK
True when the return deadline has been reached or passed (computed at read time); false when no deadline is set.
false
Creator-contact email.
"ops@example.com"
Creator-contact phone.
"+5511999999999"
JDPI creation timestamp (RFC 3339 UTC).
"2024-01-01T12:00:00.000Z"
ISPB of the recovery creator.
"12345678"
EndToEndId of the root transaction being recovered.
"E1234567820240101000000000000001"
Value-recovery GUID (the natural key).
"b2c3d4e5-f6a7-8901-bcde-f23456789012"
Situation code (0..5).
0
Human-readable situationType label.
"Golpe/Estelionato"
stRecValores lifecycle code (0=created .. 6=cancelled).
0
Human-readable stRecValores label.
"Criada"
JDPI last-modification timestamp (RFC 3339 UTC) — the watermark.
"2024-01-01T12:05:00.000Z"
Free-text detail (required when situationType=4 Outros).
"Suspected scam."
idCorrelacao — the DICT support identifier for this consultar call; quote it to JD when disputing whether the read happened.
"a9f13566e19f5ca51329479a5bae60c5"
dtHrRetornoDict — when DICT answered this consultar (contract 2.21).
"2025-08-27T10:30:05.025Z"
Creator-side 72h return deadline (RFC 3339 UTC; contract §2.22/§5), from the analysis stage close; null unless this institution is the creatorIspb on an analyzed recovery.
"2024-01-04T12:00:00.000Z"

