Quickstart

Put your sandbox values in environment variables, so every command below works as written. Use single quotes, so the shell doesn't change any character.

export MG_BASE_URL='https://api-gateway-uat.mmacs.io/platform'
export MG_API_KEY='paste-your-sandbox-api-key'   # starts with mgk_sandbox_
export MG_WEBHOOK_URL='https://your-tunnel-address.example/webhooks/multigate'

These names are used throughout the docs: MG_BASE_URL is the sandbox address that every path is added to, MG_API_KEY is sent in the mp-api-key header of every request, and the next steps add MG_CLIENT_ID, MG_ACCOUNT_ID, MG_VIRTUAL_ACCOUNT_NUMBER, MG_ACCOUNT_NUMBER and MG_REQUEST_ID.

Typing a key into a terminal can leave it in your shell history. That's acceptable for a sandbox key on your own computer; in your own code, load the key from a secrets manager.

The API key needs no sign-in and doesn't expire: send it as it is. Check that it works, find your client ID (the ID of your business on Multigate) and check your permissions:

CURRENT_USER=$(curl -s "$MG_BASE_URL/user-service/api/v1/users/current-user" \
  -H "mp-api-key: $MG_API_KEY")
export MG_CLIENT_ID=$(echo "$CURRENT_USER" | jq -r '.currentAuthenticatedClientId')
echo "$CURRENT_USER" | jq '{currentAuthenticatedClientId, permissions: [.permissions[].permissionId]}'

{
  "currentAuthenticatedClientId": "Ab3kP9xQ2mN7vR1sT4uV6",
  "permissions": ["can_initiate_payment", "can_refresh_client_api_credentials", "can_view_accounts"]
}

Check that the list contains can_refresh_client_api_credentials, can_view_accounts (or manage_accounts) and can_initiate_payment.

More causes: When a request returns 401.

Tell Multigate where to send events. Do this before anything else: events that happen while no URL is registered are lost.

curl -s -X POST "$MG_BASE_URL/client-service/api/v1/client-configurations" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg clientId "$MG_CLIENT_ID" --arg webhookUrl "$MG_WEBHOOK_URL" \
        '{mode: "sandbox", clientId: $clientId, webhookUrl: $webhookUrl}')" \
  | jq '{message, mode, webhookUrl}'

{ "message": "Client configuration updated successfully", "mode": "sandbox", "webhookUrl": "https://your-tunnel-address.example/webhooks/multigate" }

mode is only a label. Your business has one webhook URL per environment: the last configuration saved wins. If your business already saved one (check with Get client configurations), reuse its mode. Don't print the full response: it contains your client key and secret in encrypted form.

An account (also called a wallet) holds a balance in one currency. Payers fund it through its virtual accounts: real bank account numbers, listed in fundingDetails, that credit the wallet. List your active NGN wallets:

ACCOUNTS=$(curl -s "$MG_BASE_URL/client-service/api/v1/accounts?currencies=NGN&statuses=active&accountTypes=wallet&pageSize=20" \
  -H "mp-api-key: $MG_API_KEY")
echo "$ACCOUNTS" | jq '.data[] | {accountId, accountName, virtualAccountNumbers: [.fundingDetails[].accountNumber]}'

{
  "accountId": "Ac4mW8pZ2kR6tY1nQ7xVb",
  "accountName": "Acme Payments Ltd",
  "virtualAccountNumbers": ["9912345678"]
}

Keep the first wallet that has a virtual account number:

export MG_ACCOUNT_ID=$(echo "$ACCOUNTS" | jq -r '[.data[] | select(.fundingDetails | length > 0)][0].accountId')
export MG_VIRTUAL_ACCOUNT_NUMBER=$(echo "$ACCOUNTS" | jq -r '[.data[] | select(.fundingDetails | length > 0)][0].fundingDetails[0].accountNumber')
echo "$MG_ACCOUNT_ID $MG_VIRTUAL_ACCOUNT_NUMBER"

An inflow is money received into an account. In the sandbox, you add money by simulating a payment into the virtual account number:

curl -s -X POST "$MG_BASE_URL/client-service/api/v1/webHook/publishInflow" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"accountNumber\":\"$MG_VIRTUAL_ACCOUNT_NUMBER\",\"amount\":1000000,\"currency\":\"NGN\"}"

{ "message": "inflow initiated" }

amount is in naira (major units): 1000000 is ₦1,000,000.00. The response only means the inflow was queued. It is then screened and credited, which can take a few minutes. Your webhook receiver then prints an event whose header.notification_type is account and header.notification is inflow, and your business contact email receives a "Payment Received" email.

Wait for the inflow webhook, then check the balance. This also gives you the wallet's own account number (accountNumber), which this Quickstart pays from. (A virtual account number also works as the source: Multigate debits the wallet it belongs to.)

curl -s "$MG_BASE_URL/client-service/api/v1/accounts/NGN/balance?entityId=$MG_ACCOUNT_ID" \
  -H "mp-api-key: $MG_API_KEY" | jq '.accountBalance'
export MG_ACCOUNT_NUMBER=$(curl -s "$MG_BASE_URL/client-service/api/v1/accounts/NGN/balance?entityId=$MG_ACCOUNT_ID" \
  -H "mp-api-key: $MG_API_KEY" | jq -r '.accountBalance.accountNumber')

{ "accountNumber": "1029384756", "availableBalance": "1000000", "bookBalance": "1000000" }

availableBalance is what you can spend now. It must cover the payout plus its fee (₦25,000 plus about ₦50 below).

• Balance is "10000" instead of "1000000"? For some sandbox accounts the simulated amount is read in kobo (hundredths of a naira) and credited at one hundredth. Repeat step 5 with 100000000.
• Balance is "0"? The inflow hasn't been credited yet, or the balance couldn't be read. Wait a minute and check again.

Every payout carries a uniqueRequestId: your own unique ID for this payment. If a request times out, you look the payment up by this ID instead of sending it again, so it is never paid twice (Idempotency). It must be unique across all of Multigate, so include something of your own. Send ₦25,000 to a test beneficiary (the person or business you pay):

export MG_REQUEST_ID="qs_${MG_CLIENT_ID}_$(date +%s)"
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 "{
    \"uniqueRequestId\": \"$MG_REQUEST_ID\",
    \"reference\": \"Quickstart payout\",
    \"amount\": 25000,
    \"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\"
    }
  }" | jq '{transactionId, uniqueRequestId, status, amount, charge}'

bankBicOrCode is the beneficiary bank's code (058 is a Nigerian bank code; see List banks). reference needs at least 5 characters.

{
  "transactionId": "PMT-261010-093000482913",
  "uniqueRequestId": "qs_Ab3kP9xQ2mN7vR1sT4uV6_1791660000",
  "status": "pending",
  "amount": "25000.00",
  "charge": "50.00"
}

Store transactionId (Multigate's ID for the payout) with your uniqueRequestId. The payout isn't finished yet: pending means it is being screened, and it then moves to processing and finally completed or failed. The fee (charge) is taken from your account on top of amount.

All payout errors: Payouts.

Your webhook receiver gets an event with header.notification_type transfer and header.notification transfer_completed (or transfer_failed), carrying the same uniqueRequestId. In the sandbox this can take 15 minutes or more, and the test bank decides whether it completes or fails. Both are fine for this test.

You can also check at any time:

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

{ "transactionId": "PMT-261010-093000482913", "status": "completed", "responseCode": "00", "responseMessage": "Successful" }

completed and failed are final. A payout that stays pending or processing isn't failed: keep waiting, or see Transfer statuses.