Skip to main content
SPI manages Pix transfers, refunds, asynchronous outcomes, and the MED 2.0 Block Balancer. It calls Midaz for the ledger action that corresponds to the operation.
Cash-in and cash-out callback routes are adapter-only. In this release, the supplied mock provider is the supported way to exercise them. A client application must not post a callback or claim a provider settlement result.

​
Send a cash-out in two stages

A cash-out is intentionally split into initiation and processing.
  1. Call Initiate transfer with a new X-Idempotency value. The plugin validates the request and creates a transfer initiation.
  2. Call Process transfer for that initiation. The plugin performs the required Midaz debit and submits work to the mock provider.
  3. Read the transfer with Get transfer. Processing acceptance is not a final payment result.
  4. Let the mock provider deliver the terminal callback. Read again until the transfer is completed, rejected, or otherwise terminal under the response contract.
Keep the same idempotency value only for a retry of the same call. A new business payment needs a new value.

​
Receive a cash-in through the adapter boundary

The adapter receives the external-side event, calls the plugin’s internal approval and settlement callbacks, and the plugin validates and credits the destination through Midaz. Your application observes this flow through public transfer reads; it does not invoke approval or settlement callbacks. A cash-in that cannot be approved or settled is not a client-side retry decision. Inspect the public operation state and the mock test evidence before taking another action.

​
Create and observe a refund

Use Create refund against an eligible transfer, then read it through Get refund. A refund follows its own asynchronous lifecycle. Do not mark it complete until the plugin records the terminal provider outcome and the matching Midaz effect.

​
Use the MED 2.0 Block Balancer

The Block Balancer holds funds for a contested transaction before a refund decision. It is a controlled operational flow, not a shortcut for ordinary transfers.
  1. Create a hold for the contested transaction. The plugin places a pending Midaz hold from the available balance into the configured blocking account. A replay of the same request_ref returns the existing hold.
  2. If the case ends before settlement, release a PENDING hold. A hold already settling cannot be released.
  3. Start Phase 1 settlement for one hold or an eligible group. The hold becomes SETTLING; the branch either returns the pending hold and submits a refund or commits the hold, handles any surplus, and submits the required payment.
  4. Complete Phase 2 only from the linked operation’s observed outcome. A success makes the hold SETTLED; a failure compensates it to PENDING.
  5. Use manual close, surplus return, and audit functions only through authorized operational controls. They are not normal application endpoints.
The Block Balancer enforces a ceiling across its own settlements and regular outbound refunds for the same original transaction. Do not try to calculate around that protection in the client. For the DICT-side infraction and funds-recovery workflow, see DICT.