Guides
Cross-Border Transfers
Sending money across currencies : quote, exchange, payout in one flow.
A cross-border transfer converts currency and pays out internationally in one auditable pipeline.
Cross-border FX pipeline flow
sequenceDiagram
autonumber
participant Merchant as Merchant App
participant OuiPay as OuiPay API
participant FX as FX Rates Engine
participant Hold as Wallet Hold Engine
participant Payout as International Payout Rail
Merchant->>OuiPay: POST /v1/exchange/quotes (NGN -> GHS)
OuiPay->>FX: Lock rate for 60 seconds
OuiPay-->>Merchant: Quote Object (rate, quote_id, expires_at)
Merchant->>OuiPay: POST /v1/transfers (quote_id, beneficiary_id)
OuiPay->>Hold: Reserve NGN source funds (Hold State: active)
OuiPay->>FX: Execute atomic two-legged conversion
OuiPay->>Payout: Dispatch GHS payout to Ghana Bank/Momo
Payout-->>OuiPay: Payout Confirmed
OuiPay->>Hold: Convert hold to ledger debit
OuiPay-->>Merchant: Webhook (transfer.completed)1. Get an FX quote
Lock an exchange rate before initiating payout:
curl https://api.ouipay.com/v1/exchange/quotes \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"from_currency": "NGN",
"to_currency": "GHS",
"from_amount_minor": 500000
}'2. Submit the cross-border transfer
Pass the quote_id along with the destination beneficiary details:
curl https://api.ouipay.com/v1/transfers \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: xb-8842" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "01M2S17...",
"beneficiary_id": "01M2S17...",
"amount_minor": 500000,
"currency": "NGN",
"quote_id": "01M2S18..."
}'Compliance on borders
Cross-border flows enforce strict AML and sanction screening. If a transfer is flagged, compliance stage errors are raised (COMPLIANCE_DENIED). Do not retry denied compliance transfers.