Account Updater Setup
Test Tenant Onboarding
Account Updater is an Enterprise feature, and access can be requested from your test tenant in the Basis Theory Portal under Settings/Quotas.
Once enabled, your test tenant will be configured to use the Account Updater sandbox, providing stubbed responses without forwarding requests to card networks. See Account Updater Testing for more information.
Production Tenant Onboarding
Account Updater is an Enterprise feature, and access can be requested from your production tenant in the Basis Theory Portal under Settings/Quotas. 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 |
|---|---|
| Merchant Full Business Name | The complete legal name of the business as registered with the relevant government or regulatory authority. This should match the name used in official documentation, such as tax filings or business licenses. |
| Parent Company Name (if applicable) | The name of the parent company that owns or controls the merchant business, if applicable. This name can be the same as the merchant name if there is no separate parent entity. |
| Internet Address | The primary website URL or domain name associated with the merchant’s business (e.g., www.example.com). This should be the official online presence where customers can access information about the business or make purchases. |
| Merchant Category Code(s) MCC | A four-digit code defined by payment card networks (e.g., Visa, Mastercard) that classifies the merchant’s business type based on the primary goods or services offered. For example, 5812 for restaurants or 5651 for retail clothing stores. |
| Merchant Descriptor(s) | The business name or description that appears on the customer’s credit card or bank statement after a transaction. This should be clear, recognizable, and typically includes the merchant’s name or a shortened version to help customers identify the charge. |
And by collecting the following card network information from your acquirer(s):
| Network | Field Name | Description |
|---|---|---|
| Visa | Acquirer BIN | A 6-8 digit number assigned to the Acquirer that issued the merchant’s accounts, used to facilitate transaction processing. This number typically begins with a 4 and is registered with Visa for identification purposes. |
| Visa | Card Acceptor ID (CAID) | A unique identifier assigned by Visa and used by card networks and banks to designate the specific location or terminal of the merchant’s card acceptance, ensuring accurate transaction routing. |
| Mastercard | Merchant ID | A unique identifier assigned by the acquirer to the merchant for Mastercard transactions, often matching the Card Acceptor ID, used to track and process payments associated with the merchant’s business. |
| Amex | Establishment Number (SE Number) | The unique identifier assigned by American Express to the merchant in a Direct relationship. |
| Discover | Merchant ID | The unique identifier assigned by Discover to the merchant, necessary for receiving account updates from Discover. This ID ensures accurate tracking and processing of transactions associated with the merchant’s business. |
We understand that sharing merchant information, such as Acquirer BIN, Card Acceptor ID, or Merchant IDs, 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 Account Updater 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 Account Updater 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 Account Updater 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.
Application Setup
Create a Private Application for your backend system to perform Account Updater operations within your tenant.
Batch Permissions
account-updater:job:createaccount-updater:job:read
Click here to create a Private Application for use with Batch Account Updater.
Real-Time Permissions
account-updater:real-time:invoke
Click here to create a Private Application for use with Real-Time Account Updater.
Webhook Configuration
You need to configure a webhook endpoint to receive notifications for batch job status changes.
Use the webhook management API or the Portal to register an endpoint URL to receive one or more of the following Account Updater events: