Beneficiaries

A beneficiary is a person or business you pay. Save one, then send transfers with its beneficiaryId instead of repeating the bank details every time.

When to use it

Saving is optional. Create a transfer also accepts full beneficiaryDetails, and in that case Multigate saves the beneficiary for you (or reuses the matching saved one), with the same checks as below. So your beneficiary list also contains everyone you paid with beneficiaryDetails.

Save beneficiaries yourself when you want to check and approve bank details once, before the first payment.

Prerequisites

• An API user with the manage beneficiaries permission to save, update and delete, or view beneficiaries to list and read.
• The beneficiary's bank code from List banks, or the bank's BIC (SWIFT code: the 8- or 11-character international bank identifier, for example GTBINGLA).

IDs you'll use

Save a beneficiary

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

{
  "message": "beneficiary successfully validated",
  "nameEnquiryResponse": { "accountName": "ADA OKAFOR", "bankName": "Guaranty Trust Bank" }
}

curl -X POST "$MG_BASE_URL/client-service/api/v1/beneficiaries" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "Ab3kP9xQ2mN7vR1sT4uV6",
    "name": "Ada Okafor",
    "accountName": "ADA OKAFOR",
    "accountNumber": "0123456789",
    "bankBicOrCode": "058",
    "bankName": "Guaranty Trust Bank",
    "currencyIso3Code": "NGN",
    "country": "NGA",
    "addressLine1": "12 Marina Road",
    "city": "Lagos",
    "state": "Lagos"
  }'

{
  "message": "beneficiary created",
  "beneficiary": {
    "entityId": "Bn4kQ8rT2vX6yZ1aC3dEf",
    "name": "Ada Okafor",
    "accountName": "ADA OKAFOR",
    "accountNumber": "0123456789",
    "bankBicOrCode": "058",
    "bankName": "Guaranty Trust Bank",
    "bankCountry": "NGA",
    "currencyIso3Code": "NGN",
    "country": "NGA",
    "postCode": "000000",
    "status": "active",
    "clientEntityId": "Ab3kP9xQ2mN7vR1sT4uV6",
    "subClientId": "",
    "isPlatformAccount": false,
    "beneficiaries": []
  }
}

{
  "uniqueRequestId": "po_20261010_0002",
  "reference": "Supplier payment Oct",
  "amount": 125000,
  "sourceCurrencyIso3Code": "NGN",
  "sourceAccountNumber": "1029384756",
  "beneficiaryId": "Bn4kQ8rT2vX6yZ1aC3dEf"
}

Rules by currency

Every save needs clientId, name, accountName, accountNumber, bankBicOrCode, bankName, currencyIso3Code, country, addressLine1, city and state. What goes in the bank fields depends on the currency:

bankBicOrCode must match a bank in Multigate's bank list. The saved code is normalised: the local bank code for NGN, GHS, ETB and XOF, the bank's BIC for other currencies, so it can differ from what you sent. For a local code, country must be the bank's country. The name you send in accountName is saved as it is; it isn't compared with the bank's.

• Upper-case codes. Send currencyIso3Code and country in upper case. A lower-case currency is saved as sent and treated as international, so an NGN account isn't checked.
• Letters and digits only in accountNumber: no spaces or dashes.
• Duplicates. The same account number, currency and bank can be saved once per business and once per customer (409 "beneficiaries already exist"). An 8-character BIC and its 11-character XXX form count as the same bank.
• Email. Production refuses disposable email domains such as yopmail.com ("Email domain is not allowed").

Beneficiaries for your customers

Add subClientId (the customer ID) when you save a beneficiary for one of your customers. That beneficiary belongs to the customer: use it for the customer's payouts.

• Listing. List beneficiaries returns only your own business's beneficiaries unless you pass the customer ID in clientEntityId.
• Reading, updating, deleting. Today these endpoints only find your own business's beneficiaries. For a customer's beneficiary they return 400 "beneficiary not found". Read it through the list instead; to change its bank details, save a new beneficiary.

Statuses

A saved beneficiary is always active. Deleted beneficiaries are no longer returned.

Some international payout channels need the beneficiary registered with them before they pay. Multigate does this automatically the first time you pay the beneficiary through such a channel, and shows the registration as an entry in the beneficiary's beneficiaries array. The transfer stays processing until the registration is ready, and fails (with the money returned) if it's refused.

stateDiagram-v2
    direction LR
    [*] --> processing: first transfer through the channel
    processing --> active: channel accepts the beneficiary
    processing --> failed: channel refuses it
    active --> [*]
    failed --> [*]

Updating a beneficiary discards its registrations, so the next transfer through that channel waits again. In the sandbox, registrations can take much longer than in production.

How it works

sequenceDiagram
    autonumber
    participant You as Your backend
    participant MG as Multigate
    participant Bank as Beneficiary's bank
    You->>MG: POST /beneficiaries/validate (NGN)
    MG->>Bank: Name enquiry
    Bank-->>MG: Account name
    MG-->>You: 200, nameEnquiryResponse
    You->>MG: POST /beneficiaries
    MG->>MG: Check bank code, duplicates
    MG->>Bank: Account check (NGN)
    MG-->>You: 200, beneficiary active
    You->>MG: Create a transfer with beneficiaryId
    MG-->>You: 200, transfer processing

Check an account

Manage beneficiaries

Errors and recovery

Beneficiaries send no webhooks or emails.

Next steps

• Payouts: pay a saved beneficiary.
• Bulk payouts: pay many beneficiaries at once.
• Acting for your customers: customer IDs and onBehalfOf.