Refund operations

Handle Pix refund edge cases via BTG — distributed partial refunds (devoluções) across internal accounts and unblocking operations stuck in PROCESSING.

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 in PROCESSING

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

---

POST /v1/transfers/{transfer_id}/refunds
{
  "amount": "1000.82",
  "description": "MED Cappta",
  "operations": [
    { "accountAlias": "alias-conta-cliente", "amount": "0.82" },
    { "accountAlias": "alias-conta-fee", "amount": "1000.00" }
  ]
}

• 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

---

Rule	Error
sum(operations[].amount) must equal amount	400 PIX-0447 Operations Sum Mismatch
accountAlias must not repeat within the request	400 PIX-0448 Duplicate Account Alias
each amount must be greater than 0	400 PIX-0004 Invalid Field Values
each amount must have at most 2 decimal places	400 PIX-0004 Invalid Field Values
the request must contain at most 50 operations	400 PIX-0013 Limit Exceeded
the original cash-in must exist	404 PIX-0425 Cashin Not Found

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 — Cappta

---

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 before BTG confirms it. The refund or transfer then stays stuck in PROCESSING, and Midaz still holds the funds. Two endpoints re-query BTG and drive the operation to its terminal state.

Method	Endpoint	Unblocks
POST	/v1/refunds/{refund_id}/unblock	A refund stuck in PROCESSING
POST	/v1/transfers/{transfer_id}/unblock	A transfer stuck in PENDING/PROCESSING

Both require the X-Account-Id header.

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.

POST /v1/refunds/{refund_id}/unblock
X-Account-Id: <account-id>

The response includes the updated refund, a message, and the btgStatus.

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.

Operation	Default (strict)	With allowNotFoundUnblock: true
Transfer (/v1/transfers/{id}/unblock)	Returns an error	Reverts the Midaz hold (best-effort, idempotent), marks the cashout FAILED with BTG_NOT_FOUND, emits a CASHOUT outbound webhook, and returns 200 with btgStatus: "NOT_FOUND"
Refund (/v1/refunds/{id}/unblock)	Returns PIX-1012 (ErrProviderRefundNotFound)	Reverts the hold and drives the refund to its terminal state

POST /v1/transfers/{transfer_id}/unblock
{
  "allowNotFoundUnblock": true
}

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 limitation

---

The transfer unblock flow resolves state by querying BTG. It does not apply to intra-PSP (internal) transfers, which have no BTG transaction. 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