Transfer Flow

End-to-end architecture of a transfer

This page describes exactly what happens from the moment a transfer is submitted to when funds land in a recipient's bank account.

---

Overview

Partner API call
      ↓
 POST /api/payouts/transfer
      ↓
 Unique USDC deposit address issued
      ↓
 Partner sends USDC on-chain
      ↓
 Platform detects on-chain deposit (5–10 min)
      ↓
 Funds converted at locked FX rate
      ↓
 Outgoing transfer created and funded
      ↓
 Funds delivered to recipient bank/mobile wallet
      ↓
 Status → completed

---

Step-by-Step

1. Quote lock

GET /api/payouts/quote returns a real-time mid-market FX rate locked for 5 minutes. The response includes:

• quoteId — required for transfer creation

• txFee — fixed USD fee ($2 under $1,000 / $3 at or above $1,000)

• netUsdAmount — amount after fee deduction

• eurAmount — EUR equivalent after conversion

• Estimated targetAmount in the recipient's currency

• Delivery estimate

2. Transfer intent

POST /api/payouts/transfer validates the quote, verifies recipient ownership, and issues a unique USDC deposit address for this transfer. No two transfers share the same deposit address — this is how each on-chain deposit is matched to the correct transfer record.

The response includes expires_at. Send USDC before this timestamp.

3. On-chain USDC deposit

Send exactly amount USDC from source_wallet to escrow_wallet. Any supported chain is accepted:

Chain	Notes
Base	Recommended — lowest fees, fast confirmation
Arbitrum	Low fees
Optimism	Low fees
Polygon	Low fees
Ethereum Mainnet	Higher gas, slower
Solana	Fast, low fees

The platform scans for the deposit continuously. Confirmation typically takes 5–10 minutes after the transaction is included in a block.

4. Conversion

Once the deposit is confirmed, funds are converted from USDC to the target fiat currency at the rate locked in step 1. Conversion uses institutional FX liquidity with a mid-market spread.

5. Outgoing transfer

An outgoing transfer to the recipient's bank account (or mobile wallet) is created and funded automatically. No further action is required from the partner.

6. Settlement

Settlement time depends on the payment rail:

Rail	Settlement
Local bank transfer (most currencies)	Instant – same day
M-PESA (KES)	Instant
UPI (INR)	Instant
SEPA/IBAN (EUR, GBP, others)	Same day
ACH (USD)	1–2 business days
SWIFT	5–7 business days

7. Completion

status transitions to completed. If you have an email address on file for the recipient, a notification is sent.

---

Transfer Statuses

Status	Description
pending	Transfer created, awaiting USDC
awaiting_deposit	Deposit address issued, monitoring on-chain
deposit_sent	USDC confirmed on-chain
processing	Funds converting and routing to recipient
completed	Funds delivered to recipient's bank
failed	Error — see error field; contact support with transfer_id

---

Concurrent Transfers

Multiple transfers can be in flight simultaneously — for the same account or different accounts. Each transfer has a unique deposit address and is settled independently. There is no serialization or per-user lock.

---

Failure Handling

The platform automatically retries internal routing steps. If a transfer reaches failed status, the error field contains a description. Contact support at [e-mail] with the transfer_id for resolution.

Transfers that fail before USDC is sent can be cancelled via POST /api/payouts/transfer/cancel and retried with a fresh quote.

---

Idempotency

Pass a customer_uuid in the transfer request body to enable safe retries. If you submit the same customer_uuid twice, the second request returns 409 Conflict with the original transfer details — no duplicate is created.