Customers

Onboard the businesses you serve, so you can open accounts, convert and pay out for them. The API calls a customer a sub-client. Multigate checks each customer (KYB, know your business: verifying the company, its owners and its documents) before it can transact.

When to use it

Use customers when you hold money or make payments for other businesses: a fintech's or marketplace's merchants, a remittance company's business clients, a bank's corporate clients, or a corporate's subsidiaries. If you only move your own money, you don't need customers.

There are two types:

Before you start

• You've completed the Quickstart environment setup: MG_BASE_URL, MG_API_KEY and MG_CLIENT_ID (your client ID).
• Your own business must be active and approved on Multigate.
• Your API user needs the manage customers permission. To skip the second approver, it also needs the approve customers permission (see the submit step below).
• Your webhook URL is registered, so you receive the review outcome (client / subclient_approved).
• Have the customer's registration details, its directors and beneficial owners (people who own or control it, usually 25% or more), and its KYB documents as PDF or image files.

IDs you'll use

Every example below uses customer ID Kx81mQ2pZr4tV9wYa3Bc5 and person ID Hq3vT8nLm2Xc5RzW: replace them with yours.

How onboarding works

sequenceDiagram
    autonumber
    participant You as Your backend
    participant MG as Multigate
    participant AP as Your approver
    participant CO as Multigate compliance
    You->>MG: POST create customer
    MG-->>You: entityId, status draft
    You->>MG: POST add each director and owner
    You->>MG: POST upload each document
    You->>MG: POST submit for review
    MG-->>You: approval request, customer now processing
    alt Your API user can't approve customers
        MG->>AP: Email "Sub-client Creation Request for Approval"
        AP->>MG: Approve in the dashboard
    end
    MG->>MG: Screen the business name
    alt Nothing found
        MG-)You: Webhook client / subclient_approved, status active
    else Possible match
        MG->>CO: Review
        CO->>MG: Approve or decline
        MG-)You: Webhook client / subclient_approved, status active or rejected
    end

A subsidiary skips screening: it becomes active as soon as it's approved in your business, and no webhook is sent.

curl -X POST "$MG_BASE_URL/client-service/api/v1/clients/$MG_CLIENT_ID/sub-clients" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subClientType": "client",
    "businessName": "Kola Stores Ltd",
    "businessType": "Limited Liability Company",
    "customerType": "corporate",
    "businessAddressLine1": "4 Allen Avenue",
    "city": "Ikeja",
    "state": "Lagos",
    "countryOfRegistration": "NGA",
    "operatingCountries": ["NGA"],
    "businessContactEmail": "finance@kolastores.example",
    "registrationNumber": "RC1234567"
  }'

{
  "message": "Sub-Client information saved successfully",
  "entityId": "Kx81mQ2pZr4tV9wYa3Bc5",
  "businessName": "Kola Stores Ltd",
  "subClientType": "client",
  "status": "draft",
  "approvalStatus": "pending",
  "stagesRemaining": ["documentation", "director", "owner"],
  "parentClientId": "Ab3kP9xQ2mN7vR1sT4uV6"
}

curl -X POST "$MG_BASE_URL/client-service/api/v1/clients/$MG_CLIENT_ID/sub-clients/Kx81mQ2pZr4tV9wYa3Bc5/business-users" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mrs", "firstName": "Adaeze", "lastName": "Kola", "gender": "female",
    "occupation": "Director", "dateOfBirth": "1980-04-12",
    "identificationType": "PASSPORT", "identificationNumber": "A01234567",
    "issuedDate": "2022-01-10", "expiryDate": "2032-01-09",
    "countryIso3Code": "NGA", "country": "Nigeria",
    "address": "4 Allen Avenue", "city": "Ikeja", "state": "Lagos", "postalCode": "100001",
    "designation": "BeneficialOwnerDirector", "shareholderPercentage": 60
  }'

curl -X POST "$MG_BASE_URL/client-service/api/v1/clients/$MG_CLIENT_ID/sub-clients/Kx81mQ2pZr4tV9wYa3Bc5/upload-kyc" \
  -H "mp-api-key: $MG_API_KEY" \
  -F "file=@certificate.pdf" \
  -F "documentType=CERTIFICATE_OF_INCORPORATION" \
  -F "issueDate=2019-03-14"

curl -X POST "$MG_BASE_URL/client-service/api/v1/clients/$MG_CLIENT_ID/sub-clients/Kx81mQ2pZr4tV9wYa3Bc5/upload-kyc" \
  -H "mp-api-key: $MG_API_KEY" \
  -F "file=@adaeze-passport.pdf" \
  -F "documentType=PASSPORT" \
  -F "businessUserId=Hq3vT8nLm2Xc5RzW" \
  -F "issueDate=2022-01-10" \
  -F "expiryDate=2032-01-09"

curl -X POST "$MG_BASE_URL/client-service/api/v1/clients/$MG_CLIENT_ID/sub-clients/Kx81mQ2pZr4tV9wYa3Bc5/submit-for-approval" \
  -H "mp-api-key: $MG_API_KEY"

Customer statuses

stateDiagram-v2
    direction LR
    [*] --> draft: created
    draft --> processing: submitted
    draft --> active: subsidiary approved at once
    processing --> active: screening clear, compliance approves, or subsidiary approved
    processing --> rejected: compliance declines
    processing --> inactive: your approver declines, customer removed
    rejected --> processing: resubmitted
    active --> inactive: deactivated
    inactive --> active: reactivated
    active --> deleted: deleted
    active --> blocked: blocked by Multigate
    blocked --> active: unblocked by Multigate

Deactivating, reactivating and deleting customers are dashboard actions that go through your approvers. Accounts are opened only for active customers ("Sub-Client not active" otherwise).

approvalStatus shows approval inside your business only: pending (created, or waiting for your approver), approved (approved in your business; Multigate's review may still be running) or declined (declined by your approver). It stays approved when Multigate compliance declines the customer. Always use status for the outcome.

The subclient_approved webhook

The body is the customer, as returned by Get a customer: entityId, businessName, status, approvalStatus, parentClientId (your client ID) and the other customer fields.

• Sent: for a client customer, when screening finds nothing (status active) or when Multigate compliance decides (active or rejected), including after a resubmission.
• Not sent: for subsidiaries, when your approver declines, while compliance is still reviewing, or for creating, updating, uploading or submitting.
• approvalComments and approvalDate appear only after a compliance decision. approvalDate isn't ISO 8601 (it looks like Sat Oct 10 2026 14:20:00 GMT+0000 (Coordinated Universal Time)).
• De-duplicate by entityId and status: the same outcome can arrive more than once.

Things to know

• Active customers become usable for payouts and conversions after a short delay (up to a few minutes) while the change reaches those services. Until then, payouts for them fail with "Invalid sub onBehalfOf".
• Updates aren't reviewed. Update a customer works in any status and applies at once. It doesn't check country codes, prohibited countries or email uniqueness, so send the same kind of values you'd send on create.
• Countries. A customer registered or operating in a country Multigate prohibits is refused when you create it ("The selected country or countries are prohibited"). Use upper-case ISO 3166-1 alpha-3 codes.
• Email domains. Production refuses disposable email domains (yopmail.com, mailinator.com and similar) for the customer and its people. The sandbox accepts them.
• Emails go to your business. Approval requests go to your approvers, and approval results ("Subclient Creation Request Approved", "Sub-client Creation Request Declined") go to the user who submitted, which is your API user. Customers never receive emails from these steps.

Errors

Next