Concepts

Acting for your customers

If you serve other businesses, you can open accounts, save beneficiaries, convert and pay out for each of them with your own API credentials. Each customer's accounts and records are kept separate from yours.

Before you start, create the customer: see Customers. Most actions also need it to be active (see below).

Your client ID and your customers' IDs

ID	What it identifies	Where you get it
Client ID	Your business.	`currentAuthenticatedClientId` in Get the current user.
Customer ID	One of your customers (the API calls them sub-clients).	The `entityId` returned by Create a customer, or listed by List customers.

flowchart TD
    you[Your business<br/>client ID Ab3kP9xQ2mN7vR1sT4uV6] --> c1[Customer Kola Stores<br/>customer ID Kx81mQ2pZr4tV9wYa3Bc5]
    you --> c2[Customer Lumen Trading<br/>customer ID Pq72nB5cXe8dW3vU]
    c1 --> a1[(NGN account)]
    c1 --> a2[(USD account)]
    c2 --> a3[(NGN account)]
    you --> a0[(Your own accounts)]

Only active customers

You can open accounts, pay out and convert for a customer only once its status is active (see Customer statuses). A newly approved customer can take a few minutes to become usable for payouts and conversions. Beneficiaries can already be saved while the customer is draft or processing.

Which field to send

Add the customer ID to act for that customer. Leave it out to act for your own business. Most endpoints call it onBehalfOf; beneficiaries call it subClientId (to save one) or clientEntityId (to list them).

To	Send	In
Open an account	`onBehalfOf`	the body of Create an account
List accounts or account currencies	`onBehalfOf`	the query of List accounts or List currencies you hold
Save a beneficiary	`subClientId`	the body of Create a beneficiary
List beneficiaries	`clientEntityId`	the query of List beneficiaries. You can pass several IDs separated by commas.
Pay out	`onBehalfOf`	the body of Create a transfer, or the form of Preview a bulk transfer
Quote a fee	none	Get a transfer fee uses the source account's owner: pass the customer's account
Find transfers	`onBehalfOf`	the query of Find transfers. You can pass several IDs separated by commas.
Convert	`onBehalfOf`	the query of Get a quote and the body of Lock a rate

curl -X POST "$MG_BASE_URL/client-service/api/v1/accounts" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "uniqueRequestId": "acct_kola_ngn", "currencyIso3Code": "NGN", "accountName": "Kola Stores", "onBehalfOf": "Kx81mQ2pZr4tV9wYa3Bc5" }'

What Multigate checks

Action	Check	Error when it fails
Open an account	The customer exists and is `active`.	"Sub-Client not found", "Sub-Client not active"
Pay out	The customer is one of your `active` customers.	"Invalid sub onBehalfOf" or "Invalid onBehalfOf"
Pay out	The account you debit belongs to that customer.	"Invalid Source Account Owner"
Convert	The customer belongs to you, and both accounts belong to it.	"Invalid onBehalfOf id", "Invalid source or target account"
Find transfers, list beneficiaries	IDs that aren't yours are ignored.	None: you get an empty list (or only your own records).

Conversions also use the entityId header

The conversion endpoints identify your business through an entityId header. Set it to your client ID and pass the customer in onBehalfOf. A value that isn't one of your businesses returns 403. Without the header, the service uses the business your API key belongs to.

Known issue: today conversions with onBehalfOf are refused with 400 "Invalid onBehalfOf id". See FX conversions.

What you receive for customer activity

Webhooks for every customer go to your webhook URL. Tell customers apart with onBehalfOf (transfers), clientId / entityId (accounts) or the receiving account number (inflows). Customer review outcomes arrive as client / subclient_approved.
Emails about customer activity, such as "Payment Received", go to your business contact, not to the customer.
Fees are charged to the account you debit, so a customer's payout fee comes out of the customer's account.

Common mistakes

Forgetting onBehalfOf on a payout from a customer's account. The payout is checked as your own business's, and is refused with "Invalid Source Account Owner".
Listing accounts without onBehalfOf. You get only your own business's accounts, not your customers'.
Using the customer ID as your client ID. Your client ID (from Get the current user) identifies your business; send it only where an endpoint asks for your client ID.

Customers can't use the API themselves

Only your API user calls the API. Customers have no credentials of their own: you act for them.