Skip to main content
The Pix Indirect Plugin (BTG) processes Pix refunds (devoluções) through the Refund a Received Pix Transfer endpoint. Two capabilities extend that flow for MED and fraud scenarios:
  • 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 each accountAlias for its amount in 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-Idempotency key for the same account and transfer is refused with 422 PIX-3004 when the request body differs from the first one, or when the first refund failed on its create call.
  • An X-Return-End-To-End that belongs to a refund with a different request, or to a FAILED refund, is refused with 409 PIX-0423.
  • While a request with the same X-Idempotency key is still being processed, a resend is refused with 409 PIX-3002. Retry after the Retry-After interval.
  • When the first request under an X-Idempotency key ran but its outcome was not recorded, a resend is refused with 422 PIX-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 CONFIRMED or ERROR → 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.
A consistency guard aborts the operation if BTG’s entity, returnIdentification, or originalEndToEndId diverge from the local record. This prevents settlement against the wrong transaction.
The response includes the updated 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 PENDING and 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 500 after 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.
allowNotFoundUnblock defaults to false. An empty or absent body, or false, preserves the strict behavior. A BTG 404 then returns an error and never reverts the hold. Opt in only when you have confirmed that the operation must be released.
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