> For the complete documentation index, see [llms.txt](https://docs.verygoodsecurity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verygoodsecurity.com/cmp/platform/vgs-for-platforms-multi-mid-merchant-service-onboarding.md).

# VGS for Platforms (Multi-MID) - Merchant Service Onboarding

## Multi-MID merchant service onboarding

Use this guide to plan CMP onboarding for a multi-MID platform model.

It covers merchant structure, service accounts, TRIDs, and tenant design.

### Introduction

Start by deciding how each sub-merchant enrolls with the card networks.

That decision drives your account model, tenant model, and service setup.

{% hint style="info" %}
Continue to [VGS for Platforms (Multi-MID) - Implementation Guide](/cmp/platform/vgs-for-platforms-multi-mid-implementation-guide.md) after you finalize your merchant structure, TRID strategy, and tenant model.
{% endhint %}

***

### Onboarding flow

{% stepper %}
{% step %}

### Understand the CMP hierarchy

CMP supports platforms, PayFacs, merchant aggregators, and ISVs that manage credentials across multiple merchants through one integration.

Before you choose an onboarding model, align on the three core CMP entities:

* **Organization** — Your top-level company entity. It contains users, accounts, service accounts, and billing relationships.
* **Account** — Your merchant-level operating entity. It is where merchant enrollment happens and where CMP services are managed.
* **Tenant** — Your storage and configuration boundary. Token storage, service configuration, and scoped access are tenant-specific.

In a multi-merchant model, platforms often create one CMP account per merchant.
{% endstep %}

{% step %}

### Choose a multi-merchant structure

Sub-merchants that register individually with the networks, or exceed volume thresholds, usually need their own CMP account, tenant, and service account.

Platforms can choose from several supported models.

{% tabs %}
{% tab title="Dedicated Account" %}
**Dedicated account per merchant**

Each merchant gets its own CMP account, tenant, and service account.

{% hint style="info" %}
Best for merchants above TRID volume thresholds.
{% endhint %}
{% endtab %}

{% tab title="Shared Account" %}
**Shared account**

Multiple sub-merchants share one CMP account and one tenant under a single TRID.

This works best for merchants below the thresholds.

If your platform acts as a PayFac, you can often process low-volume merchants under the highest-level MID. Otherwise, CMP usually maps one merchant to one MID.

{% hint style="info" %}
The same PAN enrolled across multiple merchants produces a different `card_id` for each merchant.

Plan to reconcile lifecycle updates across those card objects.
{% endhint %}
{% endtab %}

{% tab title="Universal CMP Account" %}
**Universal CMP account**

This is the Master Data Tenant pattern.

A designated main tenant acts as the shared token store and central index for cross-merchant data reuse.

This pattern lets you associate an existing card record with additional merchants without duplicating the full storage model across separate tenants.

{% hint style="info" %}
Direct CMP aliasing is tenant-specific.

Use this pattern when you need cross-merchant deduplication.
{% endhint %}
{% endtab %}

{% tab title="Hybrid Model" %}
**Hybrid model**

This combines shared and dedicated structures.

Low-volume sub-merchants use a shared account and shared TRID.

High-volume sub-merchants use dedicated CMP accounts, dedicated tenants, and dedicated TRIDs.

{% hint style="info" %}
This is common for PayFac and ISV structures.
{% endhint %}
{% endtab %}
{% endtabs %}

| Model                 | Best for                                             | Tenant                                                                                 | Service account                                                                         | TRID                                                                    |
| --------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Dedicated account     | Simple multi-MID structures on one platform          | One tenant per merchant                                                                | One per merchant tenant                                                                 | One per merchant                                                        |
| Shared account        | Low-volume sub-merchants under TRID thresholds       | One shared tenant                                                                      | One shared account, or one per sub-merchant in the same tenant                          | One shared platform TRID                                                |
| Universal CMP account | Platforms that need cross-merchant token portability | One main tenant plus sub-merchant CMP accounts                                         | One per sub-merchant CMP account, plus one for the main tenant                          | Shared when merchants stay below thresholds                             |
| Hybrid model          | ISVs and PayFacs with mixed merchant sizes           | Shared tenant for low-volume merchants and dedicated tenants for high-volume merchants | Shared access for low-volume merchants and dedicated accounts for high-volume merchants | Shared for low-volume merchants and dedicated for high-volume merchants |

#### Additional considerations

* **MoR vs. PayFac** — Merchant of Record platforms can register on behalf of sub-merchants and may use a shared tenant. PayFacs can process low-volume sub-merchants under the highest-level MID.
* **Brands are not merchants** — If multiple brands share credentials, each brand still needs its own merchant registration, tenant, and TRID.
* **Shared PANs create multiple card objects** — If the same PAN is enrolled across multiple merchants, CMP creates a different `card_id` for each merchant.
  {% endstep %}

{% step %}

### Register network services

To start network service registration, a VGS team member shares the **CMP Enablement Form** and password through 1Password.

{% hint style="info" %}
The form submitter needs CMP Dashboard access.

Only verified users in your VGS organization receive access. Organization administrators can invite additional users as needed.

See [Manage Users](https://docs.verygoodsecurity.com/enterprise-platform/access-management/manage-users).
{% endhint %}

Select the CMP services you want to enable in the form.

If you do not have all network details yet, save the form as a draft and finish it later.

Merchants above network thresholds must enroll individually with their own network values.

Merchants below the thresholds usually do not need a separate form.

#### Enrollment rules by service

**Network Tokens**

* For **Visa**, **Mastercard**, and **Discover**, sub-merchants can enroll under a shared platform-level TRID.
* PayFacs can process low-volume sub-merchants under the highest-level MID.

**Account Updater**

* Sub-merchants below the thresholds can enroll with the platform at the TRID level.
* Visa uses a threshold of under `$1M` per year.
* Mastercard uses a threshold of under `$10M` per year.
* Merchants above those thresholds must enroll individually.

#### Network values required during onboarding

| Scope             | Network Tokens                                                                                                                                                                    | Account Updater                                                                                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Main organization | <p>Visa — optional <code>CAID + BIN</code><br>Mastercard — optional <code>Acquirer BIN/ID</code><br>Amex — required <code>SEID</code><br>Discover — required <code>MID</code></p> | Not used                                                                                                                                                                          |
| Sub-accounts      | <p>Visa — optional <code>CAID + BIN</code><br>Mastercard — optional <code>Acquirer BIN/ID</code><br>Amex — required <code>SEID</code><br>Discover — required <code>MID</code></p> | <p>Visa — required <code>CAID + BIN</code><br>Mastercard — required <code>Acquirer BIN/ID</code><br>Amex — required <code>SEID</code><br>Discover — required <code>MID</code></p> |

{% hint style="info" %}
Only Direct Account merchants are eligible for Network Tokens and Account Updater.

OptBlue participants are not supported.

VGS verifies eligibility by submitting the merchant SEID to Amex and confirming Direct status and, when available, Top of Chain.
{% endhint %}

#### 3D Secure

If each merchant processes transactions as the merchant of record, place each merchant in its own CMP account and tenant for 3DS.

Merchants can still live under one shared organization.

VGS enables 3DS at the CMP account level. A single shared merchant setup does not provide the merchant-level data segregation required for individual Merchants of Record.
{% endstep %}

{% step %}

### Configure service accounts

#### How service accounts work in CMP

CMP requires a separate service account for each merchant that uses a dedicated tenant.

The dashboard does not support one service account across multiple sub-merchants.

Network Token scopes can be assigned to only one tenant per service account.

#### Service account checklist

* [ ] Generate a new production service account for CMP.
* [ ] Validate access to the Live API and confirm VGS Live IPs are allowlisted.
* [ ] Assign the required [OAuth 2.0 scopes](/cmp/platform/authentication.md): `cards`, `accounts`, `network_tokens`, `merchants`.
* [ ] Confirm your backend can generate a production access token.
  {% endstep %}
  {% endstepper %}

***

### Token Requestor IDs

#### What is a TRID?

A Token Requestor ID, or TRID, is a network-assigned identifier used during Network Token enrollment.

Each network assigns TRIDs per merchant as part of its review process.

VGS does not issue shared or aggregate TRIDs.

#### Network Tokens vs. Account Updater

| Service         | Identifier used                                                             |
| --------------- | --------------------------------------------------------------------------- |
| Network Tokens  | TRID for Visa and Mastercard, `SEID` for Amex, and `MID` for Discover       |
| Account Updater | Acquiring BIN plus `CAID` for Visa, `SEID` for Amex, and `MID` for Discover |

{% hint style="info" %}
Account Updater does not use a TRID.

It uses separate network identifiers for enrollment.
{% endhint %}

#### Volume thresholds for shared TRIDs

Sub-merchants can enroll under a shared platform TRID when they remain within the applicable network thresholds.

| Network    | Threshold             |
| ---------- | --------------------- |
| Visa       | Under `$1M` per year  |
| Mastercard | Under `$10M` per year |
| Discover   | No threshold          |
| Amex       | No threshold          |

Merchants above these thresholds should use a dedicated TRID, dedicated tenant, and dedicated CMP account.

{% hint style="info" %}
Thresholds apply independently by network.

For example, a merchant processing `$7M` in Visa volume and `$4M` in Mastercard volume needs a dedicated TRID for Visa, but can remain on a shared TRID for Mastercard.
{% endhint %}

{% hint style="info" %}

#### Recommended architecture for platforms

The hybrid model is a common fit for ISVs and platforms:

* Enroll lower-volume merchants under a shared platform TRID.
* Register higher-volume merchants individually with dedicated tenants, TRIDs, and CMP accounts.

This balances operational simplicity with network compliance.
{% endhint %}

#### TRID request process by network

| Network    | Method                                     | Speed      |
| ---------- | ------------------------------------------ | ---------- |
| Visa       | API                                        | A few days |
| Mastercard | API                                        | A few days |
| Amex       | Manual. Requires a Direct Merchant `SEID`. | Variable   |
| Discover   | Requires Discover `MID`.                   | Variable   |

***

### Tenant architecture

#### Shared vs. dedicated tenant architecture

Your tenant architecture should match your TRID model.

| Scenario                              | Recommended setup                                           |
| ------------------------------------- | ----------------------------------------------------------- |
| Sub-merchants under volume thresholds | Shared account with a platform TRID                         |
| Sub-merchants above volume thresholds | Dedicated account, dedicated CMP tenant, and dedicated TRID |
| Migrating from a prior VGS setup      | Create a new tenant when possible                           |

#### Migrate from a prior VGS setup

If you are migrating card files from an earlier VGS CALM setup, create a new tenant instead of enabling CMP on an existing tenant when possible.

Reusing an older tenant can inherit a pre-existing merchant ID and create configuration conflicts.

Starting with a new tenant gives you a cleaner onboarding path.

{% hint style="warning" %}
You can migrate existing card files between tenants through an SFTP workflow.

See [Migrating Cards on File to VGS](https://docs.verygoodsecurity.com/vault/guides/migrations) for details.
{% endhint %}

#### How VGS uses the tenant

The tenant is the token store that maps aliases to the underlying PAN.

Because token resolution is tenant-specific, service accounts with Network Token scopes are also tenant-specific.

This means:

* Each merchant with Network Tokens enabled needs a service account scoped to its tenant.
* Multiple low-volume merchants can share a single tenant, but that model requires careful configuration management.

***

### Go-live checks

Before you submit your production onboarding request, confirm the following:

* **Correct tenant selected** — Enable CMP on the correct tenant and environment.
* **Routes promoted to production** — Route configuration does not carry over between environments.
* **Multiple merchants per organization** — If you are onboarding more than one merchant in one organization, ensure `allow_multiple_onboarding: true` is set in the onboarding YAML.
* **Webhook routing** — Confirm Account Updater events route to the correct merchant context. One endpoint does not automatically handle all sub-merchants.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verygoodsecurity.com/cmp/platform/vgs-for-platforms-multi-mid-merchant-service-onboarding.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.