Remittance

For remittance companies, that is licensed international money transfer operators (IMTOs): pay out remittances to beneficiaries' bank accounts with the sender and beneficiary details that regulators require.

When to use it

Use remittance instead of Create a transfer when the money comes from an individual sender abroad and you must record who sent it. A remittance always pays from your own business's account; it can't be sent on behalf of a customer.

Before you start

• MG_BASE_URL, MG_API_KEY and MG_ACCOUNT_NUMBER (an account number of your source account, from List accounts) are set, as in the Quickstart.
• NGN remittances are paid from a remittance collection account that Multigate sets up for your business. Ask your Multigate contact before you go live. Without it, NGN remittances are accepted and then fail.
• Fund the source account for the amount plus the fee.
• Check the beneficiary's account with Look up an account name. A remittance doesn't check it for you.
• Your API user needs the initiate payment or approve payment permission.

How it works

sequenceDiagram
    autonumber
    participant You as Your backend
    participant MG as Multigate
    participant Bank as Beneficiary bank
    You->>MG: POST /transfer/name-enquiry (beneficiary account)
    MG-->>You: Account name
    You->>MG: POST /transfer/remittance (sender, beneficiary, uniqueRequestId)
    MG-->>You: 200, data.status pending, pending_approval or processing
    MG->>Bank: Payment
    Bank-->>MG: Result
    MG-)You: transfer / transfer_completed or transfer_failed

A remittance follows the same rules as a payout: balance check, fees, screening, your approval rules, the same statuses and the same webhooks. The differences:

Send a remittance

Generate a uniqueRequestId (unique across Multigate, with your own prefix) and store it before you call. Then send the remittance:

export MG_REQUEST_ID="acme_rm_$(uuidgen | tr 'A-Z' 'a-z')"
curl -s -X POST "$MG_BASE_URL/payment-service/api/v1/transfer/remittance" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "uniqueRequestId": "$MG_REQUEST_ID",
    "sourceAccountNumber": "$MG_ACCOUNT_NUMBER",
    "currencyIso3Code": "NGN",
    "amount": 180000,
    "narration": "Family support Oct",
    "sender": {
      "firstName": "John", "lastName": "Mensah",
      "emailAddress": "john.mensah@example.com", "phoneNumber": "+447700900123",
      "address": "10 High Street", "city": "London", "countryIso3Code": "GBR"
    },
    "beneficiary": {
      "firstName": "Ama", "lastName": "Mensah",
      "accountName": "Ama Mensah", "accountNumber": "0123456789",
      "bankBicOrCode": "058", "bankName": "Guaranty Trust Bank", "countryIso3Code": "NGA"
    }
}
EOF

{
  "message": "Successful",
  "data": {
    "transactionId": "PMT-261010-170000903311",
    "uniqueRequestId": "acme_rm_5c2e8f10-7a4b-4d3e-9f21-6b0c1d2e3f4a",
    "status": "processing",
    "amount": "180000.00",
    "currencyIso3Code": "NGN",
    "sourceAccountNumber": "1029384756",
    "narration": "Family support Oct",
    "sender": { "firstName": "John", "lastName": "Mensah", "countryIso3Code": "GBR" },
    "beneficiary": { "accountName": "Ama Mensah", "accountNumber": "0123456789", "bankBicOrCode": "058", "countryIso3Code": "NGA" }
  }
}

The remittance is nested under data, unlike single transfers. failureReason appears when status is failed. Store data.transactionId with your uniqueRequestId, then follow Payouts › After you send: the webhooks, polling and timeout handling are the same.

• Required: uniqueRequestId, sourceAccountNumber, currencyIso3Code, amount, narration, sender.firstName, sender.lastName, beneficiary.accountNumber, beneficiary.accountName, beneficiary.bankBicOrCode, beneficiary.countryIso3Code.
• Send all the sender details you hold (address, phone, email, country, and BVN for Nigerian senders). They're used for compliance screening.
• Beneficiary fields are limited to those in Initiate a remittance. Others, such as address (use addressLine1) or bankCountryIso3Code, are silently dropped.
• Narration is shortened to 36 characters. When Multigate sends the payment to the bank, it adds its own transactionId after your narration (Family support Oct PMT-…), so every payout can be matched to the bank's records during reconciliation. Some banks show only the start of a long narration, so put what the beneficiary must see first.
• Track it with Get a remittance by transactionId or uniqueRequestId, or with Find transfers.

Statuses

stateDiagram-v2
    direction LR
    [*] --> pending
    [*] --> pending_approval
    [*] --> processing
    pending --> processing
    pending --> failed
    pending_approval --> pending
    pending_approval --> rejected
    processing --> completed
    processing --> failed

Emails

Remittances send no "Transfer Notification" emails. The only email is "Transaction Declined", if an approver in your business declines one.

Errors

The 400 errors are the same as payout errors, plus:

After a timeout or 5xx, look the remittance up by uniqueRequestId before retrying. See Idempotency.

Next

• Remittance companies (IMTOs): the end-to-end flow.
• Event catalogue for the transfer webhooks.