Cross-border payouts

Pay suppliers, contractors or partners abroad from your local-currency balance: convert NGN to USD at a locked rate, then pay out by international bank transfer (SWIFT, the network banks use to send money abroad).

Who it's for: corporate enterprises and SMEs paying suppliers abroad, and fintechs offering international payouts.

Architecture

flowchart LR
    you[Your backend] -->|1 quote and lock| fx[FX conversion]
    ngn[(Your NGN account)] -->|debited sourceAmount| fx
    fx -->|credited targetAmount| usd[(Your USD account)]
    you -->|2 create transfer| usd
    usd -->|SWIFT payment| bank([Supplier's bank abroad])
    fx -.->|trade_completed| hook[Your webhook endpoint]
    usd -.->|transfer_completed or transfer_failed| hook

sequenceDiagram
    autonumber
    participant You as Your backend
    participant MG as Multigate
    participant Bank as Supplier's bank abroad
    You->>MG: Get a transfer fee (USD account, supplier amount)
    You->>MG: Get a quote NGN to USD (amount = supplier amount + fee)
    MG-->>You: Quote id, buyRate, endTime (about 60 seconds)
    You->>MG: Lock the rate (quote id, NGN accountId, USD accountId)
    MG-->>You: status completed (or processing)
    MG-)You: trade / trade_completed
    You->>MG: Create a transfer from the USD account (SWIFT, chargeType, assets)
    MG-->>You: 200, status pending (screening)
    Note over MG: Screening, approval, debit, then payment
    MG->>Bank: SWIFT payment
    MG-)You: transfer / transfer_completed or transfer_failed

Before you start

• A sandbox API key, and the variables MG_BASE_URL, MG_API_KEY and MG_CLIENT_ID set as in the Quickstart.
• A webhook URL registered (Webhooks overview). Events that happen before you register it are never delivered.
• Your API user has the lock rates permission (to convert) and the initiate payment permission (to quote fees and pay). See Approvals for whether its payments also need an approver.
• Multigate has set up partner banks for NGN and USD for your business, and you have accepted their terms of service in the dashboard.
• Supporting documents. A USD payout to an account whose name doesn't match your own account name is a third-party payment and needs supporting documents, such as the supplier's invoice. Paying a supplier is almost always third-party. The upload endpoint isn't public yet: ask Multigate how to upload documents and get their IDs.

Build plan

curl "$MG_BASE_URL/payment-service/api/v1/transfer/get-transfer-fee?amount=18000&sourceCurrencyIso3Code=USD&sourceAccountNumber=4410023391&beneficiaryId=Bn4kQ8rT2vX6yZ1aC3dEf" \
  -H "mp-api-key: $MG_API_KEY"

{ "message": "Successful", "feeAmount": 25, "feeCurrency": "USD", "isFeePercentage": false, "transactionCharge": 25, "beneficiaryWillReceive": 18000 }

curl "$MG_BASE_URL/trade-service/api/v1/fx-rates/best-rate?sourceCurrency=NGN&targetCurrency=USD&amount=18025" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "entityId: $MG_CLIENT_ID"

curl -X POST "$MG_BASE_URL/trade-service/api/v1/fx-rates/lock-rate" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "entityId: $MG_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "FX-261010-150000482913",
    "sourceAccountId": "Ac4mW8pZ2kR6tY1nQ7xVb",
    "targetAccountId": "Ac7tY2nQ5xVb9mW3pZ8kR",
    "amount": 18025,
    "reference": "acme_conv_20261010_0007"
  }'

curl -X POST "$MG_BASE_URL/payment-service/api/v1/transfer/single-transfer" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uniqueRequestId": "acme_po_20261010_0003",
    "reference": "Invoice LT-2026-118",
    "amount": 18000,
    "sourceCurrencyIso3Code": "USD",
    "sourceAccountNumber": "4410023391",
    "beneficiaryId": "Bn4kQ8rT2vX6yZ1aC3dEf",
    "paymentMethod": "SWIFT",
    "chargeType": "SHA",
    "assets": ["3c9d7e21-5b4a-4f6e-8a1d-2e7f9c0b6a51"]
  }'

Choose who pays SWIFT charges

chargeType isn't validated, so send one of these values exactly. Multigate's own fee is separate and always charged to your account on top of the amount.

Data to store

Webhooks to handle

Some outcomes send no webhook: a decline by your approver (rejected), a compliance decline (failed, responseCode 43) and a debit that couldn't be posted (failed, 03). Poll Find transfers ?uniqueRequestId= for payouts that stay non-final. See Outcomes without a webhook.

Reconciliation

Each day, pull Get an account statement for both accounts (Balances and statements):

• NGN account: a Trade debit of sourceAmount per conversion.
• USD account: a Trade credit of targetAmount per conversion, and a Transfer debit per payout with customReference = your uniqueRequestId, plus its fee.

Anything only in your records is usually a payout still in a non-final status; anything only in the statement is usually a webhook you didn't process.

Things that trip people up

• The transfer currency must match the source account: you can't pay USD from an NGN account. Convert first.
• The balance isn't reserved when you create the transfer; it's checked just before the debit. Keep the USD in the account until the payout is final: if it's short at that check, the payout ends failed (22, with a webhook), and if it drops right after the check, failed (03) without one.
• In the sandbox an unfunded lock succeeds; production refuses it with 402 "Insufficient balance". Check the NGN balance before you lock. See Sandbox vs production.
• Never lock a second quote for the same payout until you've confirmed the first didn't go through: a quote ID is the only retry key for a conversion.

Go-live notes

• Agree USD payout pricing and the supporting-document process with Multigate.
• Decide with your admin who approves payouts (maker-checker: one person creates, another approves), and test the pending_approval path.
• Re-test an FX lock larger than your balance in production on day one and handle the 402.
• Work through the go-live checklist.