Tenant Merchants

Tenant Merchants enable organizations with multiple business units, regional entities, or sub-merchants to manage independent service configurations within a single Tenant. Each Tenant Merchant holds its own merchant details, card network identifiers, and per-service onboarding state for services like Account Updater and Network Tokens.

Create Tenant Merchant

Create a Tenant Merchant within the Tenant.

POST

https://api.basistheory.com/tenants/{tenantId}/merchants

Permissions

tenant:merchant:create

Request

cURL

curl "https://api.basistheory.com/tenants/e4e865b2-304e-4179-a040-9f8b3cd8bedb/merchants" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
--data '{
  "name": "Acme",
  "details": {
    "merchant": {
      "full_legal_name": "Acme, Inc.",
      "doing_business_as": "Acme",
      "parent_company_name": "Acme Holdings",
      "website_url": "https://www.acme.com",
      "category_code_mcc": "5734",
      "descriptor": "ACME.COM",
      "business_description": "Online software and digital goods",
      "registration": {
        "registration_type": "EIN",
        "registration_id": "12-3456789"
      },
      "contact": {
        "name": "Jane Doe",
        "title": "Head of Payments",
        "phone_number": "+14155552671",
        "email": "jane@acme.com"
      },
      "address": {
        "street_1": "123 Main Street",
        "city": "Anytown",
        "state_province": "CA",
        "postal_code": "94016",
        "country": "US"
      }
    },
    "card_network_info": {
      "visa": { "acquirer_bin": "400000", "card_acceptor_id_caid": "123456789012345" },
      "mastercard": { "merchant_id_mid": "987654321" },
      "amex": { "se_number": "1234567890" },
      "discover": { "merchant_id_mid": "555555555" }
    }
  }
}'

URI Parameters

Parameter	Required	Type	Default	Description
tenantId	true	uuid	null	The ID of the Tenant

Request Parameters

Attribute	Required	Type	Default	Description
name	true	string	null	Display name of the Tenant Merchant. Must be unique within the Tenant.
details	false	merchant details	null	Merchant information and card network identifiers used to onboard services.

Response

Returns a Tenant Merchant if created successfully. Returns an error if there were validation errors, the Tenant was not found, or creation failed.

Errors

Status	Description
400	The request body failed validation.
404	The Tenant was not found.
409	A Tenant Merchant with the same name already exists in the Tenant.

List Tenant Merchants

Get a list of Tenant Merchants for the Tenant.

GET

https://api.basistheory.com/tenants/{tenantId}/merchants

Permissions

tenant:merchant:read

Request

cURL

curl "https://api.basistheory.com/tenants/e4e865b2-304e-4179-a040-9f8b3cd8bedb/merchants" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>"

Node

await client.tenants.merchants.list();

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

const tenantMerchants = await bt.tenants.listMerchants();

C#

await client.Tenants.Merchants.ListAsync(new MerchantsListRequest());

Java

new MerchantsClient(ClientOptions.builder().build()).list();

Python

client.tenants.merchants.list()

Go

merchants, err := client.Tenants.Merchants.List(ctx, &tenants.MerchantsListRequest{})

URI Parameters

Parameter	Required	Type	Default	Description
tenantId	true	uuid	null	The ID of the Tenant

Query Parameters

Parameter	Required	Type	Default	Description
page	false	integer	1	Page number of the results to return.
size	false	integer	20	Number of the results to return per page. Maximum size of 50 results.

Response

Returns a paginated object with the data property containing an array of Tenant Merchants. Returns an error if Tenant Merchants could not be retrieved.

The details field is omitted from the response when it has not been set on the Tenant Merchant.

{
  "pagination": {...},
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "tenant_id": "8f1b2c3d-4e5f-6789-0abc-def012345678",
      "name": "Acme",
      "details": {
        "merchant": { ... },
        "card_network_info": { ... }
      },
      "services": {
        "account_updater": { "status": "active", "card_network_status": { ... } },
        "network_token":   { "status": "onboarding", "card_network_status": { ... } }
      },
      "created_by": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_at": "2024-12-01T10:30:00+00:00",
      "modified_by": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "modified_at": "2024-12-15T14:22:00+00:00"
    },
    {...},
    {...}
  ]
}

Get a Tenant Merchant

Get a Tenant Merchant by ID in the Tenant.

GET

https://api.basistheory.com/tenants/{tenantId}/merchants/{merchantId}

Permissions

tenant:merchant:read

Request

cURL

curl "https://api.basistheory.com/tenants/e4e865b2-304e-4179-a040-9f8b3cd8bedb/merchants/d290f1ee-6c54-4b01-90e6-d701748f0851" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>"

Node

await client.tenants.merchants.get("merchantId");

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

const merchant = await bt.merchants.retrieveMerchant(
  "d290f1ee-6c54-4b01-90e6-d701748f0851"
);

C#

await client.Tenants.Merchants.GetAsync("merchantId");

Java

new MerchantsClient(ClientOptions.builder().build()).get("merchantId");

Python

client.tenants.merchants.get(
  merchant_id="merchantId",
)

Go

merchant, err := client.Tenants.Merchants.Get(ctx, "merchantId")

URI Parameters

Parameter	Required	Type	Default	Description
tenantId	true	uuid	null	The ID of the Tenant
merchantId	true	uuid	null	The ID of the Tenant Merchant

Response

Returns a Tenant Merchant with the id provided. Returns an error if the Tenant Merchant could not be retrieved.

Update Tenant Merchant

Update a Tenant Merchant's name and/or details.

PATCH

https://api.basistheory.com/tenants/{tenantId}/merchants/{merchantId}

Permissions

tenant:merchant:update

Request

cURL

curl "https://api.basistheory.com/tenants/e4e865b2-304e-4179-a040-9f8b3cd8bedb/merchants/d290f1ee-6c54-4b01-90e6-d701748f0851" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-H "Content-Type: application/json" \
-X "PATCH" \
-d '{
  "name": "Acme",
  "details": {
    "merchant": { "...": "..." },
    "card_network_info": { "...": "..." }
  }
}'

URI Parameters

Parameter	Required	Type	Default	Description
tenantId	true	uuid	null	The ID of the Tenant
merchantId	true	uuid	null	The ID of the Tenant Merchant

Request Parameters

Attribute	Required	Type	Default	Description
name	false	string	null	Display name of the Tenant Merchant.
details	false	merchant details	null	Merchant information and card network identifiers.

Response

Returns the updated Tenant Merchant. Returns an error if the Tenant or Tenant Merchant could not be found, or if the update failed validation.

Delete Tenant Merchant

Delete a Tenant Merchant by ID from the Tenant.

DELETE

https://api.basistheory.com/tenants/{tenantId}/merchants/{merchantId}

Permissions

tenant:merchant:delete

Request

cURL

curl "https://api.basistheory.com/tenants/e4e865b2-304e-4179-a040-9f8b3cd8bedb/merchants/d290f1ee-6c54-4b01-90e6-d701748f0851" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-X "DELETE"

URI Parameters

Parameter	Required	Type	Default	Description
tenantId	true	uuid	null	The ID of the Tenant
merchantId	true	uuid	null	The ID of the Tenant Merchant

Response

Returns the deleted Tenant Merchant. Returns an error if the Tenant Merchant could not be deleted.

Request Service Onboarding

Request onboarding for one or more services (e.g., Account Updater, Network Tokens) across specific card networks. The system validates the required card network identifiers, registers the merchant with the upstream provider, and updates the service status to onboarding until activation completes.

POST

https://api.basistheory.com/tenants/{tenantId}/merchants/{merchantId}/services

Permissions

tenant:merchant:update

Request

cURL

curl "https://api.basistheory.com/tenants/e4e865b2-304e-4179-a040-9f8b3cd8bedb/merchants/d290f1ee-6c54-4b01-90e6-d701748f0851/services" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
  "account_updater": ["visa", "mastercard"],
  "network_token": ["visa"],
  "card_network_info": {
    "visa": { "acquirer_bin": "400000", "card_acceptor_id_caid": "123456789012345" },
    "mastercard": { "merchant_id_mid": "987654321" },
    "amex": { "se_number": "1234567890" },
    "discover": { "merchant_id_mid": "555555555" }
  }
}'

URI Parameters

Parameter	Required	Type	Default	Description
tenantId	true	uuid	null	The ID of the Tenant
merchantId	true	uuid	null	The ID of the Tenant Merchant

Request Parameters

Attribute	Required	Type	Default	Description
account_updater	false	string[]	null	Card networks to onboard for Account Updater. Valid values: visa, mastercard, amex, discover.
network_token	false	string[]	null	Card networks to onboard for Network Tokens. Valid values: visa, mastercard, amex, discover.
card_network_info	conditional	card network info	null	Card network identifiers. Required for any network being onboarded that doesn't already have identifiers stored on the merchant. Values provided here are persisted back to the merchant.

At least one service (account_updater or network_token) must be specified with one or more networks.

Response

Returns the updated Tenant Merchant with the requested services reflecting onboarding status on the requested networks.

Errors

Status	Description
400	Missing card network info for one or more requested networks.
404	The Tenant or Tenant Merchant was not found.
409	One or more (service, network) pairs are already in onboarding or active status.

Tenant Merchant Object

Attribute	Type	Description
id	uuid	Unique identifier of the Tenant Merchant.
tenant_id	uuid	The Tenant ID that this Merchant belongs to.
name	string	Display name of the Tenant Merchant. Each Tenant Merchant within a Tenant must have a unique name.
details	merchant details	Merchant information and card network identifiers collected at creation or update time.
services	services	Per-service and per-network onboarding state (e.g., Account Updater, Network Tokens).
created_by	uuid	(Optional) The ID of the User or Application that created the Tenant Merchant.
created_at	date	(Optional) Created date of the Tenant Merchant in ISO 8601 format.
modified_by	uuid	(Optional) The ID of the User or Application that last modified the Tenant Merchant.
modified_at	date	(Optional) Last modified date of the Tenant Merchant in ISO 8601 format.

Merchant Details Object

The details object groups merchant information and card network identifiers.

Attribute	Type	Description
merchant	merchant info	Core business information for the merchant.
card_network_info	card network info	Card network identifiers (BIN, CAID, MID, SE number) used when onboarding services.

Merchant Info Object

Attribute	Required	Type	Description
full_legal_name	true	string	Full legal name of the business.
doing_business_as	false	string	Doing Business As (DBA) name.
parent_company_name	false	string	Parent company name, if applicable.
website_url	true	string	Merchant website URL.
category_code_mcc	true	string	Merchant Category Code (MCC). Must be exactly four digits.
descriptor	true	string	Merchant descriptor as shown on statements. Maximum length 150.
business_description	false	string	Short description of the merchant's line of business.
registration	true	registration	Business registration information.
contact	true	contact	Primary contact for the merchant.
address	true	address	Physical address of the merchant.

Registration Object

Attribute	Required	Type	Description
registration_type	true	string	Type of business registration. Must be one of: ABN, ACN, CNPJ, BN, DIC, ICO, CVR, CRN, SIREN, SIRET, CR, CF, RC, KvK, GST, NZBN, BIR, KRS, NIP, REGON, BRN, UEN, CIF, NIF, ROC, EIN, VAT.
registration_id	true	string	Business registration identifier.
vat_id	conditional	string	VAT Identification Number. Required in jurisdictions that use VAT.

Contact Object

Attribute	Required	Type	Description
name	true	string	Primary contact name.
title	false	string	Primary contact's job title.
phone_number	true	string	Primary contact phone number in E.164 format (e.g., +14155552671).
email	true	string	Primary contact email address.

Address Object

Attribute	Required	Type	Description
street_1	true	string	Street address line 1. Maximum length 100.
street_2	false	string	Street address line 2. Maximum length 100.
city	true	string	City. Maximum length 30.
state_province	true	string	State or province. Maximum length 30.
postal_code	true	string	ZIP or postal code. Maximum length 10.
country	true	string	Country in ISO 3166-1 alpha-2 format. Two uppercase letters (e.g., US).

Card Network Info Object

Card network identifiers collected at merchant creation/update time. Identifiers are required before onboarding services that use the corresponding card network.

Attribute	Required	Type	Description
visa.acquirer_bin	conditional	string	Visa acquirer BIN. Required to onboard Visa on services that use it. Must be between 6 and 8 digits.
visa.card_acceptor_id_caid	conditional	string	Visa Card Acceptor ID (CAID).
mastercard.merchant_id_mid	conditional	string	Mastercard Merchant ID (MID).
amex.se_number	conditional	string	American Express Service Establishment (SE) number.
discover.merchant_id_mid	conditional	string	Discover Merchant ID (MID).

Services Object

The services object is always present on a Tenant Merchant and reports the onboarding state of each supported service. For a newly-created merchant that has not yet requested onboarding, each service defaults to status: "inactive" with every network also set to inactive. Each service entry has the same shape.

Attribute	Type	Description
account_updater	service status	State of the Account Updater service.
network_token	service status	State of the Network Tokens service.

Service Status Object

Attribute	Type	Description
status	string	Rolled-up service status. See Service Status Values.
card_network_status	card network status	Per-network status for visa, mastercard, amex, and discover.

Card Network Status Object

Each network (visa, mastercard, amex, discover) on card_network_status has the following shape. All fields are read-only — they are managed by Basis Theory and cannot be set or modified via the API.

Attribute	Type	Description
status	string	Network-level status. See Service Status Values.
status_reason_code, status_reason, status_reason_label	string	(Optional) Only populated when status is failed. status_reason_code is a machine-readable reason code, status_reason is the reason detail, and status_reason_label is the human-readable label resolved from status_reason_code.

Service Status Values

Status	Description
inactive	Service not enabled for this merchant.
onboarding	Onboarding data submitted; awaiting upstream provider activation.
active	Service is fully configured and operational.
failed	An error was found in the onboarding data submitted. The reason code and description are returned on the corresponding card_network_status.{network} entry.