Network Tokens Setup
Network Tokens is an Enterprise feature and the onboarding process is different between TEST and PRODUCTION Tenants. Start by requesting access from your test tenant in the Basis Theory Portal under Settings → Quotas.
Test Tenant Onboarding
Once enabled, your test tenant will be configured to use the Network Tokens sandbox, providing stubbed responses without forwarding requests to card networks. See Network Tokens Testing for more information.
Production Tenant Onboarding
Once requested, Basis Theory will reach out to complete the onboarding process and to gather the necessary merchant configuration.
You can begin preparing for this process by having the following business information ready:
| Field Name | Description |
|---|---|
| Full Legal Name | The complete legal name of the business as registered with the relevant government or regulatory authority. This must exactly match official registration records. |
| Doing Business As (DBA) | The trading name or brand name under which the business operates, if different from the legal name. This name may appear in customer-facing contexts. |
| Website URL | The primary website or domain associated with the business (e.g., https://www.example.com). This should represent the merchant’s official online presence. |
| Business Street Address | The registered street address of the business headquarters or principal place of operation. |
| Business City | The city associated with the registered business address. |
| Business Country | The country where the business is legally registered and operates. |
| Business Postal Code | The postal or ZIP code associated with the registered business address. |
| Business Registration ID | The official business registration number issued by the applicable government authority (e.g., company number, registration number, or equivalent). |
| Business Registration Type | The type of registration associated with the business (e.g., LLC, Corporation, Ltd., GmbH, Sole Proprietorship). |
| Business MCC | The four-digit Merchant Category Code (MCC) assigned by the acquirer or card networks that classifies the merchant’s primary business activity. |
| VAT Identification Number | The Value Added Tax (VAT) identification number, if applicable, used for tax and regulatory purposes in supported regions (e.g., EU VAT ID for European businesses, UK VAT Number, Brazilian CNPJ/CPF, or similar national tax identifiers). |
The following identifiers are required depending on the card networks the merchant supports. These values are typically obtained from your acquirer or directly from the network.
| Network | Field Name | Description |
|---|---|---|
| Amex | Direct SE Number | The Establishment (SE) Number assigned by American Express for merchants operating under a Direct relationship. This identifier is required for Network Token enablement with Amex. |
| Discover | MID / SE Number | The Merchant ID or Establishment Number assigned by Discover. This identifier is required to provision and manage Discover Network Tokens for the merchant. |
We understand that sharing merchant information requires careful consideration due to its sensitive nature. Rest assured, these details are securely handled and are required by the card networks (Visa, Mastercard, Amex, Discover) to successfully onboard merchants to the Network Tokens service. This service ensures seamless transaction processing by providing updated card information, benefiting both merchants and customers.
Acquirers will not incur any charges, as the card networks issue credentials directly to Basis Theory to enable access to Network Tokens functionality. To streamline onboarding, acquirers may securely provide the necessary information by emailing support@basistheory.com directly. All data shared will be used exclusively for the purpose of enabling Network Tokens services, in full compliance with industry standards and regulations.
We are committed to making this process straightforward and secure for all parties involved. For any questions or assistance, our support team is ready to help.
Tenant Configuration
The following configuration applies to both TEST and PRODUCTION Tenants after onboarding is completed.
Access Controls
Refer to the implementation guides to learn which Access Controls (applications, permissions, etc.) are required for your use case.
Webhook Configuration
You need to configure a webhook endpoint to receive real-time notifications for critical Network Token lifecycle events. This enables proactive monitoring and automated response to Network Token status changes.
Use the webhook management API or the Portal to register an endpoint URL to receive one or more of the following Network Token events:
network-token.created: Triggered when a new Network Token is successfully creatednetwork-token.cryptogram.created: Triggered when a cryptogram is generated for a Network Tokennetwork-token.deleted: Triggered when a Network Token is permanently deletednetwork-token.updated: Triggered when a Network Token is updated by the card network or the state of the Network Token is changed