Managing sub-clients

By the end of this guide, you’ll have sub-clients registered for your downstream merchants, with each user session applying the right per-merchant branding and compliance settings.

Before you start

You’ve confirmed with your Mesh representative that sub-clients are the right approach for your use case
Sub-client functionality has been enabled on your account

Overview

If Mesh is part of a product you offer to other businesses, sub-clients are how you represent each of your clients individually to Mesh. Each sub-client gets its own branding and compliance record, so the end-users of each merchant see an experience tailored to that merchant’s product rather than yours. This guide covers what sub-clients are, how to register them (via dashboard or API), and how to apply them to individual user sessions. For a concise introduction to the sub-client model, see Concepts.

What are Sub-Clients?

If your product is used directly by end-users, you can skip this guide. However, if your product is embedded within other platforms (e.g., you are a Payment Service Provider powering payments for multiple retailers), then sub-clients are critical. A Sub-Client represents the specific merchant or platform where your product is embedded, and where Mesh will be used. Registering them allows you to:

Ensure Consistent Branding: Display the specific merchant’s name and logo in the Mesh Link modal, creating a seamless experience for the end-user.
Maintain Compliance: Mesh requires visibility into the legal entity associated with each transaction for compliance purposes.

How to Register a Sub-Client

First, reach out to your Mesh representative to enable sub-client functionality for your account. Then, you can register and manage sub-clients in two ways:

Manually, via the Mesh developer dashboard
Programmatically, via Mesh’s Account Management API endpoints

Option 1: Manually, via the Mesh developer dashboard

Navigate to Account > Link Configuration > Clients tab.
Click “Add a client”.
Enter the Business Legal Name, Display Name, Callback URL(s), and upload the relevant icon.
Click Save.

Option 2: Via the Account Management API

For high-volume or automated setups, you can use a collection of Account Management API endpoints (see here) to create, read, update, and delete sub-clients. To use this API, you must first generate a dedicated API key in the developer dashboard and configure security settings.

Generate an API Key:
- Go to Account > API Keys > Account management API keys.
- Click to generate a new key.
- Use this key to authenticate your requests to the https://admin-api.meshconnect.com endpoints.
Configure IP Whitelisting (Security Requirement):
- Just like calls to any production Mesh endpoint, access to these endpoints are restricted to pre-approved IP addresses.
- Go to Account > API keys > Access and add the specific IP address ranges from which your servers will make API calls.

How to use a sub-client in a user session

Once a sub-client is registered (via Dashboard or API), you will receive a unique subClientId. To apply the sub-client’s branding and settings to a transaction, you will pass this ID in your Link Token request as shown below (payment example):

curl --request POST \
  --url https://sandbox-integration-api.meshconnect.com/api/v1/linktoken \ // This is pointing to sandbox
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \ // Replace
  --header 'X-Client-Secret: YOUR_API_KEY' \ // Replace
  --data '
{
  "subClientId": "SUB_CLIENT_ID", // Replace (the unique identifier for this registered sub-client)
  "userId": "UNIQUE_USER_ID", // Replace
  "restrictMultipleAccounts": true,
  "transferOptions": {
    "transactionId": "UNIQUE_TRANSACTION_ID", // Replace
    "transferType": "payment",
    "isInclusiveFeeEnabled": false,
    "generatePayLink": false,
    "toAddresses": [ // Replace (example array below)
      {
        "networkId": "0291810a-5947-424d-9a59-e88bb33e999d", // Solana
        "symbol": "USDC", // Replace
        "address": "xxx", // Replace
        "amount": 99.99 // Replace
      },
      {
        "networkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611", // Ethereum
        "symbol": "USDC", // Replace
        "address": "xxx", // Replace
        "amount": 99.99 // Replace
      },
      {
        "networkId": "aa883b03-120d-477c-a588-37c2afd3ca71", // Base
        "symbol": "USDC", // Replace
        "address": "xxx", // Replace
        "amount": 99.99 // Replace
      },
      {
        "networkId": "03dee5da-7398-428f-9ec2-ab41bcb271da", // Bitcoin
        "symbol": "BTC", // Replace
        "address": "xxx", // Replace
        "amount": 0.00141, // Replace
        "displayAmountInFiat": 99.99 // Replace
      }
    ]
  }
}
'

Test your implementation

Before going live, verify that sub-client branding and session routing are working end-to-end. What to test:

Branding: Launch a Link session using a Link Token that includes your subClientId. Confirm that Link displays the sub-client’s logo and display name — not your top-level account’s branding.
Fallback: Launch a session without a subClientId. Confirm that the default top-level branding appears correctly.
API path (if applicable): Create a sub-client via the Account Management API and confirm you receive a valid subClientId before using it in a Link Token request.
Sandbox first: Register a sub-client under your sandbox account and test with your sandbox credentials (https://sandbox-integration-api.meshconnect.com). Sandbox and production sub-client registrations are separate.

If sub-client branding isn’t appearing: Double-check that the subClientId in your Link Token request exactly matches the ID returned when the sub-client was created. An incorrect or missing ID silently falls back to top-level branding.

What’s next

With sub-clients registered and subClientId flowing through your Link Token requests, the natural next steps are customizing the experience further and controlling which assets each merchant’s users can access:

Polish the experience — customize themes, embed vs. overlay behavior, and other presentation options across your sub-clients

AI coding reference (llms.txt)

AI coding reference — a compact summary of this page’s APIs, parameters, and patterns for use by AI coding assistants (following the llms.txt standard). Human readers can safely ignore this.llms.txt — Managing sub-clientsRegister and manage sub-clients (child Mesh accounts) for B2B/PSP contexts where you serve multiple downstream merchants.Register via Dashboard: Account > Link Configuration > Clients > Add a client. Fields: Business Legal Name, Display Name, Callback URL(s), icon upload.Register via API: POST to Account Management API at https://admin-api.meshconnect.com. Requires separate Account Management API key (Dashboard: Account > API keys > Account management API keys) and IP allowlisting.Apply to user session: Pass subClientId in Link Token request body. Result: Link displays sub-client branding instead of top-level account branding.Testing: Register sandbox sub-clients separately from production. Use https://sandbox-integration-api.meshconnect.com for sandbox sessions.Fallback: Omitting subClientId or using incorrect value silently falls back to top-level branding — no error thrown.Use case: Required for PSPs/payment platforms serving multiple merchants. Single-product direct-to-consumer apps do not need sub-clients.Link Token with subClientId — canonical request body (payment example):

curl --request POST \
  --url https://sandbox-integration-api.meshconnect.com/api/v1/linktoken \ // This is pointing to sandbox
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \ // Replace
  --header 'X-Client-Secret: YOUR_API_KEY' \ // Replace
  --data '
{
  "subClientId": "SUB_CLIENT_ID", // Replace (the unique identifier for this registered sub-client)
  "userId": "UNIQUE_USER_ID", // Replace
  "restrictMultipleAccounts": true,
  "transferOptions": {
    "transactionId": "UNIQUE_TRANSACTION_ID", // Replace
    "transferType": "payment",
    "isInclusiveFeeEnabled": false,
    "generatePayLink": false,
    "toAddresses": [ // Replace (example array below)
      {
        "networkId": "0291810a-5947-424d-9a59-e88bb33e999d", // Solana
        "symbol": "USDC", // Replace
        "address": "xxx", // Replace
        "amount": 99.99 // Replace
      },
      {
        "networkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611", // Ethereum
        "symbol": "USDC", // Replace
        "address": "xxx", // Replace
        "amount": 99.99 // Replace
      },
      {
        "networkId": "aa883b03-120d-477c-a588-37c2afd3ca71", // Base
        "symbol": "USDC", // Replace
        "address": "xxx", // Replace
        "amount": 99.99 // Replace
      },
      {
        "networkId": "03dee5da-7398-428f-9ec2-ab41bcb271da", // Bitcoin
        "symbol": "BTC", // Replace
        "address": "xxx", // Replace
        "amount": 0.00141, // Replace
        "displayAmountInFiat": 99.99 // Replace
      }
    ]
  }
}
'

​Overview

​What are Sub-Clients?

​How to Register a Sub-Client

​Option 1: Manually, via the Mesh developer dashboard

​Option 2: Via the Account Management API

​How to use a sub-client in a user session

​Test your implementation

​What’s next

Overview

What are Sub-Clients?

How to Register a Sub-Client

Option 1: Manually, via the Mesh developer dashboard

Option 2: Via the Account Management API

How to use a sub-client in a user session

Test your implementation

What’s next