Skip to content

Fiat payout (SWIFT / Wire / ACH)

TL;DR - Pick a customer and recipient, enter the amount, review the fee breakdown, request a 6-digit code from your authenticator app, and confirm. The customer's balance is debited; the provider sends the wire. SWIFT settles in 3–5 business days; Wire in 1–3.

Before you start

You need:

  • A customer in active status with enough available balance.
  • A fiat recipient already set up - see Add a fiat recipient.
  • An authenticator app on your phone - same one you used at first login.

Step 1 - Pick the customer and recipient

From the customer dashboard click Send fiat payout, or open the global Send payout menu and pick Fiat.

The first step has two pickers:

Field Notes
Customer Searchable list of active customers. Picking one filters the recipient list to that customer.
Recipient Searchable by company / person name, email, or bank name. Each row shows a rail badge (WIRE / SWIFT), the bank name, and the masked account. ACH recipients are excluded - ACH is initiated from a different rail in v1.

Step 2 - Amount and details

Field Required Notes
Amount Yes Minimum $1.00. The available balance card to the right shows what you can spend.
Memo No Free text, included on the wire metadata.
Invoice number No Stored on the transaction for your reconciliation.
Supporting document No Upload a PDF, PNG, or JPG (≤10 MB) - invoice, contract, anything compliance might need.

Step 3 - Preview the fee breakdown

The preview card shows the three-tier fee model in full:

Line What it is
Recipient gets What hits the recipient's bank, in green.
Provider fee What the upstream provider charges Magma.
Platform fee What Magma charges your fintech.
Your markup What your fintech charges this customer.
Total fees Sum of the three layers, in red.
Total to deduct Recipient gets + total fees. Bold.

For the formula and how markups roll up, see Fee breakdown.

Step 4 - TOTP confirmation

Click Send code. The dashboard requests an OTP through the upstream provider, which delivers a 6-digit code to your phone via the same channel you enrolled at first login (typically SMS or your authenticator app - depending on what your provider has on file).

Type the 6-digit code into the modal. It's valid for ~30 seconds.

One submit only

The Confirm payout button is disabled the instant you click it and only re-enables on a server error. Combined with the idempotency key sent in the request, this is what prevents double payments from network retries.

Step 5 - Result screen

A success screen confirms the payout was queued:

Field Notes
Payout ID Internal identifier. Copyable.
Reference Human-readable code, format PO-XXXXXXXX. Include this when talking to support.
Status Initial status is pending or processing - see Status reference.
Method WIRE or SWIFT, matching the recipient's rail.
Total deducted What was taken out of the customer's available balance.
Recipient gets What hits the recipient's account.
Created Timestamp.

A settlement note reminds you of the rail's expected timeline:

  • Wire - 1–3 business days.
  • SWIFT - 3–5 business days.

Tracking the payout

The transaction shows up immediately in the transactions list, filterable by customer and status. You'll see it move through pending → processing → completed (or failed / returned).

A PDF receipt is downloadable from the transaction detail (GET /api/v1/transactions/{id}/receipt).

Double-payment prevention

Two layers:

  1. Idempotency key - every request to POST /api/v1/payouts/fiat carries a unique Idempotency-Key header. If the same key is replayed (e.g. by a network retry), the provider returns the original result rather than billing twice.
  2. UI button disabling - the Confirm button is locked the moment you click and only re-opens on a server error.

What happens behind the scenes

UI action Endpoint Required headers
Preview fees POST /api/v1/payouts/preview -
Request OTP POST /api/v1/payouts/fiat/send-otp -
Confirm payout POST /api/v1/payouts/fiat Idempotency-Key (UUID), X-OTP-Code (6 digits)

Request body fields: amount, currency (USD), recipientId, paymentRail (ACH / WIRE / SWIFT), supportingDocs. Response: amountDeducted, fees, reference (PO-XXXXXXXX), status, createdAt.

What's next