Payouts

Send money from one of your Multigate accounts to a bank account, in Nigeria or abroad, with one endpoint: Create a transfer. This page shows which request to send for your case, what happens after you send it, and how to handle every outcome.

Words used on this page

More terms are in the Glossary.

When to use it

Before you start

• You have done the Quickstart, so MG_BASE_URL and MG_API_KEY are set in your terminal. If a call returns 401, check that MG_API_KEY holds the whole key and that it hasn't been revoked (When a request returns 401).
• Your API user has the initiate payment or approve payment permission (can_initiate_payment or can_approve_payment in permissions of the current user). Without either, create calls return 403. Getting a fee quote needs initiate payment.
• You have an active source account in the currency you will send. Find it with List accounts: use one of its account numbers (fundingDetails[].accountNumber) as sourceAccountNumber, or its accountId as sourceAccountId. The Quickstart saved an NGN one in MG_ACCOUNT_NUMBER.
• The account's available balance covers the amount plus the fee (see Fees). Check it with Get an account balance. In the sandbox, add money with Simulate an inflow.
• Your webhook URL is registered, and your endpoint verifies signatures. The result of a payout arrives there.
• Paying for a customer? You have the customer ID (entityId from Create a customer), and the source account belongs to that customer (List accounts with onBehalfOf). See Acting for customers.
• USD to someone else? You need supporting documents (for example an invoice) when the beneficiary's account name doesn't match your source account's name. Ask Multigate how to upload them; you pass their IDs in assets.

How a payout works

The create call only checks and records the transfer, then answers within seconds. Everything else happens after the response:

1. Checks (during the call). Multigate checks the source account, the beneficiary, the currency, the amount limits and the fee (and your balance, for a large NGN transfer that is split, or a linked-account source). If any check fails, you get 400 and nothing is created.
2. Approval (if your business uses it). The transfer waits for an approver in your business. See Approvals.
3. Screening. Multigate checks the payment against its compliance and risk rules. Most payments clear in seconds; some are held for manual review.
4. Balance check and debit. Multigate checks that your available balance covers the amount plus the fee, then debits it. If the balance is too low, the transfer ends failed (responseCode 22) with a transfer_failed webhook, and nothing is debited. Your balance isn't reserved before this point.
5. Payment. The money is sent to the beneficiary's bank on the right rail.
6. Result. You receive a transfer_completed or transfer_failed webhook.

sequenceDiagram
    autonumber
    participant You as Your backend
    participant MG as Multigate
    participant Bank as Beneficiary bank
    You->>MG: POST /transfer/name-enquiry (optional, local)
    MG-->>You: Account name
    You->>MG: GET /transfer/get-transfer-fee (optional)
    MG-->>You: Fee
    You->>MG: POST /transfer/single-transfer (uniqueRequestId)
    Note over MG: Check account, beneficiary, limits and fee
    MG-->>You: 200 OK, status pending, pending_approval or processing
    Note over MG: Your approval rules, then compliance screening
    Note over MG: Check balance, then debit amount and fee
    MG->>Bank: Send payment on the chosen rail
    Bank-->>MG: Result
    MG-)You: Webhook transfer_completed or transfer_failed

Choose your request

Every request has the same core fields. What changes is how you describe the beneficiary.

The beneficiary's currency must be the source account's currency. To pay in another currency, convert first.

Request fields

beneficiaryDetails needs name, accountName, accountNumber, bankBicOrCode, currencyIso3Code, countryIso3Code, addressLine1, city and state. The full list, with lengths, is in Create a transfer.

Send a payout

curl -s "$MG_BASE_URL/payment-service/api/v1/banks?countryIso3Code=NGA&bankName=guaranty" \
  -H "mp-api-key: $MG_API_KEY" \
  | jq '.data[] | {bankName, bankCode, swift_code, isActive}'

curl -s -X POST "$MG_BASE_URL/payment-service/api/v1/transfer/name-enquiry" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bankCode": "058", "bankAccountNumber": "0123456789", "currencyIso3Code": "NGN", "countryIso3Code": "NGA" }'

{
  "message": "Successful",
  "responseCode": "00",
  "responseMessage": "Successful",
  "status_code": "00",
  "status_desc": "successful",
  "bankAccountName": "ADA OKAFOR",
  "bankAccountNumber": "0123456789",
  "bankName": "Guaranty Trust Bank",
  "accountCurrency": "NGN"
}

curl -s "$MG_BASE_URL/payment-service/api/v1/transfer/get-transfer-fee?amount=250000&sourceCurrencyIso3Code=NGN&sourceAccountNumber=$MG_ACCOUNT_NUMBER" \
  -H "mp-api-key: $MG_API_KEY"

{
  "message": "Successful",
  "feeAmount": 50,
  "feeCurrency": "NGN",
  "isFeePercentage": false,
  "transactionCharge": 50,
  "beneficiaryWillReceive": 250000
}

export MG_REQUEST_ID="acme_po_$(uuidgen | tr 'A-Z' 'a-z')"

curl -s -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 @- <<EOF
{
  "uniqueRequestId": "$MG_REQUEST_ID",
  "reference": "Invoice 2026-118",
  "amount": 250000,
  "sourceCurrencyIso3Code": "NGN",
  "sourceAccountNumber": "$MG_ACCOUNT_NUMBER",
  "beneficiaryDetails": {
    "name": "Ada Okafor",
    "accountName": "ADA OKAFOR",
    "accountNumber": "0123456789",
    "bankBicOrCode": "058",
    "currencyIso3Code": "NGN",
    "countryIso3Code": "NGA",
    "addressLine1": "12 Marina Road",
    "city": "Lagos",
    "state": "Lagos"
  }
}
EOF

curl -s -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 @- <<EOF
{
  "uniqueRequestId": "$MG_REQUEST_ID",
  "reference": "Supplier payment Oct",
  "amount": 4800,
  "sourceCurrencyIso3Code": "GHS",
  "sourceAccountNumber": "$MG_GHS_ACCOUNT_NUMBER",
  "beneficiaryDetails": {
    "name": "Kofi Mensah",
    "accountName": "Kofi Mensah",
    "accountNumber": "1441000123456",
    "bankBicOrCode": "130100",
    "currencyIso3Code": "GHS",
    "countryIso3Code": "GHA",
    "addressLine1": "5 Independence Avenue",
    "city": "Accra",
    "state": "Greater Accra"
  }
}
EOF

curl -s -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 @- <<EOF
{
  "uniqueRequestId": "$MG_REQUEST_ID",
  "reference": "PO 7781 Lumen Trading",
  "amount": 18000,
  "sourceCurrencyIso3Code": "USD",
  "sourceAccountNumber": "$MG_USD_ACCOUNT_NUMBER",
  "chargeType": "SHA",
  "assets": ["3c9d7e21-5b4a-4f6e-8a1d-2e7f9c0b6a51"],
  "beneficiaryDetails": {
    "name": "Lumen Trading GmbH",
    "accountName": "Lumen Trading GmbH",
    "accountNumber": "DE89370400440532013000",
    "bankBicOrCode": "COBADEFFXXX",
    "currencyIso3Code": "USD",
    "countryIso3Code": "DEU",
    "addressLine1": "Friedrichstrasse 10",
    "city": "Berlin",
    "state": "Berlin",
    "postCode": "10117",
    "intermediaryBank": {
      "bankName": "Citibank N.A.",
      "bic": "CITIUS33XXX",
      "countryIso3Code": "USA"
    }
  }
}
EOF

curl -s -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 @- <<EOF
{
  "uniqueRequestId": "$MG_REQUEST_ID",
  "reference": "Invoice 2026-119",
  "amount": 75000,
  "sourceCurrencyIso3Code": "NGN",
  "sourceAccountNumber": "$MG_ACCOUNT_NUMBER",
  "beneficiaryId": "$MG_BENEFICIARY_ID"
}
EOF

curl -s -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 @- <<EOF
{
  "uniqueRequestId": "$MG_REQUEST_ID",
  "reference": "Kola Stores payroll Oct",
  "amount": 120000,
  "sourceCurrencyIso3Code": "NGN",
  "sourceAccountNumber": "$MG_CUSTOMER_ACCOUNT_NUMBER",
  "onBehalfOf": "$MG_CUSTOMER_ID",
  "beneficiaryDetails": {
    "name": "Tunde Bello",
    "accountName": "TUNDE BELLO",
    "accountNumber": "0234567891",
    "bankBicOrCode": "058",
    "currencyIso3Code": "NGN",
    "countryIso3Code": "NGA",
    "addressLine1": "3 Allen Avenue",
    "city": "Ikeja",
    "state": "Lagos"
  }
}
EOF

{
  "message": "Successful",
  "transactionId": "PMT-261010-093000482913",
  "uniqueRequestId": "acme_po_6f1c2a90-3b7d-4e8a-9c51-0d2e4f6a8b13",
  "reference": "Invoice 2026-118",
  "status": "pending",
  "responseCode": null,
  "responseMessage": "",
  "amount": "250000.00",
  "charge": "50.00",
  "totalAmount": "250050.00",
  "sourceAccountNumber": "1029384756",
  "sourceCurrencyIso3Code": "NGN",
  "beneficiaryId": null,
  "beneficiaryDetails": {
    "entityId": "Bn4kQ8rT2vX6yZ1aC3dEf",
    "accountName": "ADA OKAFOR",
    "accountNumber": "0123456789",
    "bankName": "Guaranty Trust Bank",
    "bankBicOrCode": "058",
    "currencyIso3Code": "NGN",
    "countryIso3Code": "NGA"
  },
  "transactionType": "DR",
  "createdAt": "2026-10-10T09:30:00.482Z"
}

After you send

The create response is never the final result. Follow these steps for every payout.

// Called after the signature check, with the parsed webhook body.
async function handleTransferEvent(event) {
  const { notification_type: type, notification } = event.header;
  if (type !== 'transfer') return;
  if (notification !== 'transfer_completed' && notification !== 'transfer_failed') return;

  const { uniqueRequestId, transactionId, responseCode, responseMessage } = event.body;
  // A split NGN transfer sends one event per part: acme_po_…-1, acme_po_…-2 (see "Large NGN transfers").
  const payout = await db.payouts.findByUniqueRequestId(uniqueRequestId);
  if (!payout) return; // not one of yours

  // Webhooks can arrive twice or out of order: never change a payout that is already final.
  if (['completed', 'failed', 'rejected'].includes(payout.status)) return;

  if (notification === 'transfer_completed') {
    await db.payouts.update(payout.id, { status: 'completed', transactionId });
  } else {
    await db.payouts.update(payout.id, { status: 'failed', transactionId, responseCode, failureReason: responseMessage });
  }
}

curl -s "$MG_BASE_URL/payment-service/api/v1/transaction/report?uniqueRequestId=$MG_REQUEST_ID,$MG_REQUEST_ID-1" \
  -H "mp-api-key: $MG_API_KEY" \
  | jq '.data[] | {uniqueRequestId, transactionId, status, responseCode, responseMessage}'

{
  "uniqueRequestId": "acme_po_6f1c2a90-3b7d-4e8a-9c51-0d2e4f6a8b13",
  "transactionId": "PMT-261010-093000482913",
  "status": "completed",
  "responseCode": "00",
  "responseMessage": "Successful"
}

curl -s -o receipt.pdf "$MG_BASE_URL/payment-service/api/v1/transaction/download-transfer-receipt/PMT-261010-093000482913" \
  -H "mp-api-key: $MG_API_KEY"

Transfer statuses

stateDiagram-v2
    direction LR
    [*] --> pending: created, screening
    [*] --> pending_approval: needs an approver
    [*] --> processing: not screened (linked account)
    pending --> processing: screening cleared
    pending --> failed: declined by compliance (43)
    pending_approval --> processing: approved (05), then screened
    pending_approval --> rejected: declined by approver
    processing --> pending: bank unreachable, retrying (31)
    processing --> completed: paid
    processing --> failed: bank, partner or debit failure
    processing --> rejected: declined in Multigate review
    completed --> [*]
    failed --> [*]
    rejected --> [*]

responseCode and responseMessage give more detail. Failures reported by the bank or partner carry their own code, for example 26 ("Invalid Account Number").

If Multigate can't confirm what happened to a payment at the bank (for example the call to the bank was interrupted, or the bank accepted it and later reported it failed), the transfer stays pending or processing and its responseMessage reads "CBI provider dispatch outcome is unknown" (or "CBI reference belongs to another request; reconcile before resolution"). Multigate's operations team reconciles it with the bank; no webhook is sent until then. Don't send the payment again with a new uniqueRequestId: that could pay twice.

Once a transfer is processing, Multigate keeps asking the bank for the result:

Fees

• On top of the amount. The beneficiary receives the full amount; your account is debited amount + charge. The fee is in the source currency.
• Quoted before, charged after. Get a transfer fee quotes it; the create response shows it as charge. It is debited with the amount, after screening and approval.
• Separate fee account. If Multigate has set up a separate fee account for your account, the fee is taken from there, and that account must cover it ("Insufficient funds in fee account" otherwise).
• Between Multigate accounts. A transfer to another Multigate account is free, unless the receiving business has opted in to a fee. It skips screening and approval, and completes as soon as Multigate's ledger records it.
• On your statement the fee is a separate Fee line (ID FEE-…) with your uniqueRequestId as customReference. See Balances and statements.
• SWIFT bank charges are separate from Multigate's fee: chargeType decides who pays the banks along the way.

Which rail is used

If you don't set paymentMethod, Multigate chooses:

flowchart TD
    start[Transfer] --> chosen{paymentMethod set?}
    chosen -->|Yes| use[Use it, if it is configured for the currency]
    chosen -->|No| linked{Source is a SWIFT linked account?}
    linked -->|Yes| swift[SWIFT]
    linked -->|No| partner{Currency paid out through a payout partner?}
    partner -->|Yes| prail[The partner's local rail, for example SEPA for EUR or FPS for GBP, otherwise SWIFT]
    partner -->|No| lcy{NGN, GHS, ETB, CNY or XOF?}
    lcy -->|Yes| local[The currency's configured local rail, NIP for NGN]
    lcy -->|No| other[The currency's configured rail, otherwise SWIFT]
    local --> big{NGN above 100,000,000?}
    big -->|Yes| split[Split into several NIP payments]

• Amounts above the currency's maximum are refused ("Maximum amount exceeded"), except NGN on NIP, which is split into at most 100 parts (larger amounts are refused). List payment methods shows the configured limits and indicative fees.
• Single transfers don't take a purpose code. Purpose codes are used in bulk payout files.
• The transfer object doesn't show which rail was used.

Large NGN transfers are split

NGN transfers above the per-payment limit of the local instant rail (100,000,000 NGN unless Multigate configures otherwise) are sent as several payments. Validate a transfer tells you in advance (splitPreview), with the exact total fee.

When a transfer is split:

• The response includes splitSummary, listing each part with its own reference (transfer ID) and uniqueRequestId: yours with -1, -2, … added. No part is stored under your original uniqueRequestId, so look parts up with ?uniqueRequestId=<yours>-1,<yours>-2. Your original ID stays reserved: sending it again is refused with "Unique request ID already exist".
• The fee is quoted once for the whole amount and shared across the parts in proportion to their amounts.
• At most 100 parts: an NGN transfer above 100 times the limit (10,000,000,000 NGN at the default limit) is refused with 400 "Maximum amount exceeded".
• Each part is its own transfer: it appears separately in Find transfers and sends its own webhook.
• Your transfer is complete when every part is completed. Parts can end differently; handle a partly paid transfer.

Approvals

If your business uses maker-checker approval, a transfer starts in pending_approval unless the API user that creates it may also approve it:

• Without an approval workflow: a transfer goes straight to screening and payment only when the API user has both the initiate payment and the approve payment permissions. Otherwise it waits for an approver.
• With an approval workflow (rules set up in the dashboard, by amount and currency): it goes straight through only when the API user is an approver for that amount and currency and the workflow needs one approval ("first to approve"). Otherwise it waits for the approvers the workflow names.

An approver approves or declines it in the Multigate dashboard:

• Approved: the transfer moves to processing (responseCode 05), is screened, then pays as normal. Your balance is checked just before the debit.
• Declined: it moves to rejected (responseCode 04, no webhook) and the creator gets a "Transaction Declined" email with the reason.

To send payments straight to processing, ask your administrator to give your API user both the initiate and the approve payment permissions, or to make it an approver in your workflow.

Errors

A 400 on create means nothing was created. Fix the request and send it again (you can keep the same uniqueRequestId, because the first attempt didn't happen). The error body is [{ "errors": { "message": "…" } }], or for a missing field a failed_validation body with an errors list (see Errors).

The full list is in Create a transfer.

When your balance is checked

So that creating a transfer is fast, Multigate doesn't check your balance when you create most transfers. It checks it just before it debits your account, after screening and approval:

What this means for you:

• Check before you send when you need an immediate answer, for example to tell a user "insufficient funds" on screen. Validate a transfer always checks the balance (amount plus fee).
• Handle transfer_failed with responseCode 22 as "not paid, nothing debited". Today its responseMessage is the raw key insufficientBalance (or insufficientFeeBalance), not a sentence, so match on the code. Fund the account, then send a new transfer with a new uniqueRequestId: the failed one keeps its ID.
• The balance isn't reserved between the check and the debit. Several payouts sent at once from the same account can each pass the check while together they need more than the balance, so keep your own running total of what you've sent.

Common mistakes

• A new uniqueRequestId on retry. After a timeout, look the payout up first. A new ID can pay twice.
• Treating the create response as the result. 200 means "accepted", not "paid". Wait for the webhook or poll.
• Relying on webhooks alone. rejected and some failures send none. Poll non-final payouts.
• Sending both beneficiaryId and beneficiaryDetails. Send one.
• Paying in a different currency from the source account. Convert first.
• Parsing amounts as floats. Amounts are decimal strings in responses; use a decimal type.
• Using a BIC for a local NGN payout, or a local code abroad. Local payouts take the bank code; international ones take the BIC.

Webhooks and emails

Next