- Distributed partial refunds: return a refund from multiple internal accounts in a single operation
- Unblock: recover a refund or transfer that is stuck before a final state. The table in the section Unblocking stuck operations lists the states each unblock accepts.
Distributed partial refunds
A received Pix can split internally across several accounts. For example, the principal amount goes to the customer account and a fee goes to a fee account. A later MED or fraud refund can then debit part of the amount from each account. The standard refund flow debits one account. To split the debit, send an optional
operations array in the request body. The operations array is the only signal. There is no new endpoint, environment variable, or feature flag.
Request
- Without
operations→ the current single-account flow runs unchanged. - With
operations→ the plugin debits eachaccountAliasfor itsamountin Midaz, and BTG receives a single pacs.004 for the total refund value.
Validation rules
Resend a refund
A refund request carries
X-Idempotency, X-Return-End-To-End, or both. A request with neither is refused with 400 PIX-0001, and no money moves.
When the first refund is not FAILED, a resend with the same anchor and the same request returns it and creates no second one, except in the case that PIX-3005 describes below.
- The same
X-Idempotencykey for the same account and transfer is refused with422PIX-3004when the request body differs from the first one, or when the first refund failed on its create call. - An
X-Return-End-To-Endthat belongs to a refund with a different request, or to aFAILEDrefund, is refused with409PIX-0423. - While a request with the same
X-Idempotencykey is still being processed, a resend is refused with409PIX-3002. Retry after theRetry-Afterinterval. - When the first request under an
X-Idempotencykey ran but its outcome was not recorded, a resend is refused with422PIX-3005. Reconcile the first refund. Do not resend it, and do not retry under a new key.
The endpoint, BTG flow (pacs.004 with the total value), idempotency, and authentication match the standard refund. Only the internal Midaz debit composition changes.
Example: fee split
The plugin split a R$ 50,000.00 cash-in: R$ 49,000.00 to the customer account and R$ 1,000.00 to a fee account. After fraud, the refund must be R$ 1,000.82. Only R$ 0.82 remains in the customer account. The
operations array debits R$ 0.82 from the customer account and R$ 1,000.00 from the fee account. BTG receives a single R$ 1,000.82 refund with no manual ledger consolidation.
Unblocking stuck operations
A reversal call to BTG can time out or fail with a server error before BTG confirms it. The refund then stays in
PENDING, and Midaz still holds the funds. Two endpoints drive a stuck operation to its terminal state.
Both require the
X-Account-Id header of the account that owns the operation.
How unblock works
The plugin re-queries the reversal or transfer status at BTG and:
- If BTG reports
CONFIRMEDorERROR→ dispatches the corresponding settlement and moves the operation to its terminal state. - If BTG still reports
INITIATED/PROCESSING→ returns HTTP 200 with no action. Retry later.
entity, returnIdentification, or originalEndToEndId diverge from the local record. This prevents settlement against the wrong transaction.
refund, a message, and the btgStatus.
When the plugin settles a cash-in or a refund cash-in more than 300 seconds after its creation, it first looks for a credit that Midaz already holds for it. If it finds one, it completes the cash-in on that credit and does not credit again. If the lookup fails, or the credit it finds was reversed, unblock fails and credits nothing.
Operations parked at CREATED
A cash-out or a cash-out refund stays at
CREATED when the plugin cannot learn the outcome of the Midaz debit. The plugin sends no Pix for it. Unblock refuses an inter-PSP cash-out or refund at CREATED with 422 PIX-0470. Open a support request with Lerian and give the transfer or refund id.
Refusals
Unblock also answers
422 PIX-0470 in these cases:
- An inter-PSP cash-out or refund is in
PENDINGand changed less than 150 seconds ago. The create call can still be sending it to BTG. Retry the call after that time. - The cash-out or the refund is already final. If an earlier call answered
500after the cash-out became final, repeat the call.
Handling a 404 from BTG
BTG can return
404 when it no longer has the reversal or transfer. The result then depends on the operation type and the opt-in allowNotFoundUnblock flag in the request body.
The opt-in 404 recovery applies only to
CASHOUT operations in PENDING/PROCESSING with a non-empty endToEndId. Cash-ins and terminal statuses never enter this branch.Intra-PSP operations
Unblock settles an intra-PSP cash-out or refund on Midaz alone and sends no query to BTG. See Intra-PSP transfers.
Next steps
- Intra-PSP transfers: Internal P2P transfers and refunds
- MED 2.0: Funds Recovery: Cross-account fraud recovery
- Webhooks: Refund and transfer event handling
- API reference: Full API documentation

