# 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](../04-products/01-customers.md). 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](api:getCurrentUser). |
| **Customer ID** | One of your customers (the API calls them sub-clients). | The `entityId` returned by [Create a customer](api:createSubClient), or listed by [List customers](api:listSubClients). |

```mermaid
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](../04-products/01-customers.md#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](api:createAccount) |
| List accounts or account currencies | `onBehalfOf` | the query of [List accounts](api:listAccounts) or [List currencies you hold](api:listAccountCurrencies) |
| Save a beneficiary | `subClientId` | the body of [Create a beneficiary](api:createBeneficiary) |
| List beneficiaries | `clientEntityId` | the query of [List beneficiaries](api:listBeneficiaries). You can pass several IDs separated by commas. |
| Pay out | `onBehalfOf` | the body of [Create a transfer](api:createSingleTransfer), or the form of [Preview a bulk transfer](api:previewBulkTransfer) |
| Quote a fee | none | [Get a transfer fee](api:getTransferFee) uses the source account's owner: pass the customer's account |
| Find transfers | `onBehalfOf` | the query of [Find transfers](api:listTransfers). You can pass several IDs separated by commas. |
| Convert | `onBehalfOf` | the query of [Get a quote](api:getFxQuote) and the body of [Lock a rate](api:lockFxRate) |

```bash
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). |

:::info[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](../04-products/09-fx-conversions.md).
:::

## 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](api:getCurrentUser)) 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.