Network Tokens Testing
Basis Theory provides a Network Tokens sandbox environment that provides stubbed responses without forwarding your requests to the card networks.
Once the feature is enabled, test tenants will be configured to use the Network Tokens sandbox, and you can use the test cards defined below to simulate various scenarios.
Planning your full integration test? See Platform Testing for how to validate each leg of the chain across Basis Theory, your PSP, and the card networks.
Test Cards
The following test cards can be used to test different error and success scenarios when creating network tokens.
| PAN | Card Brand | Response | Error Title |
|---|---|---|---|
4000000000000002 | Visa | Success | [Not Applicable] |
4000000000000085 | Visa | Success | [Not Applicable] |
4000000000000093 | Visa | Success | [Not Applicable] |
5100000000000008 | Mastercard | Success | [Not Applicable] |
5100000000000065 | Mastercard | Success | [Not Applicable] |
5100000000000073 | Mastercard | Success | [Not Applicable] |
6011000000000004 | Discover | Success | [Not Applicable] |
370000000000002 | American Express | Success | [Not Applicable] |
370000000000069 | American Express | Success | [Not Applicable] |
370000000000077 | American Express | Success | [Not Applicable] |
4012888888881881 | Visa | Provision Data Expired | PROVISION_DATA_EXPIRED |
5105105105105100 | Mastercard | Provision Data Expired | PROVISION_DATA_EXPIRED |
6011601160116611 | Discover | Provision Data Expired | PROVISION_DATA_EXPIRED |
371449635398431 | American Express | Provision Data Expired | PROVISION_DATA_EXPIRED |
4330251207506660 | Visa | Card Verification Failed | CARD_VERIFICATION_FAILED |
5461310156953048 | Mastercard | Card Verification Failed | CARD_VERIFICATION_FAILED |
6011168802268945 | Discover | Card Verification Failed | CARD_VERIFICATION_FAILED |
370488998077498 | American Express | Card Verification Failed | CARD_VERIFICATION_FAILED |
4539097887163333 | Visa | Card Not Eligible | CARD_NOT_ELIGIBLE |
5325191087030619 | Mastercard | Card Not Eligible | CARD_NOT_ELIGIBLE |
6011690151507086 | Discover | Card Not Eligible | CARD_NOT_ELIGIBLE |
373555735376156 | American Express | Card Not Eligible | CARD_NOT_ELIGIBLE |
4929980395567582 | Visa | Card Not Allowed | CARD_NOT_ALLOWED |
5580422612666704 | Mastercard | Card Not Allowed | CARD_NOT_ALLOWED |
6011444770992901 | Discover | Card Not Allowed | CARD_NOT_ALLOWED |
378025849667382 | American Express | Card Not Allowed | CARD_NOT_ALLOWED |
4929544240318920 | Visa | Card Declined | CARD_DECLINED |
5157204564548129 | Mastercard | Card Declined | CARD_DECLINED |
6011760519541711 | Discover | Card Declined | CARD_DECLINED |
348322853530243 | American Express | Card Declined | CARD_DECLINED |
4916725297925395 | Visa | Provision Not Allowed | PROVISION_NOT_ALLOWED |
5336475987107024 | Mastercard | Provision Not Allowed | PROVISION_NOT_ALLOWED |
6011490740263725 | Discover | Provision Not Allowed | PROVISION_NOT_ALLOWED |
375155165213132 | American Express | Provision Not Allowed | PROVISION_NOT_ALLOWED |
4711358892785746 | Visa | Card Eligibility Error | CARD_ELIGIBILITY_ERROR |
5233580618829955 | Mastercard | Card Eligibility Error | CARD_ELIGIBILITY_ERROR |
6011000990139424 | Discover | Card Eligibility Error | CARD_ELIGIBILITY_ERROR |
348835199015504 | American Express | Card Eligibility Error | CARD_ELIGIBILITY_ERROR |
5555555555554444 | Mastercard | Issuer Declined | ISSUER_DECLINED |
These cards are not valid for real transactions and should only be used in the Basis Theory sandbox environment. The network token value returned in the sandbox is also simulated, so your PSP or the card networks will not necessarily accept it in their own sandboxes.
Deduplication
When the same PAN is provisioned more than once within a tenant, the API returns the existing Network Token with _extras.deduplicated: true rather than creating a new one. The sandbox behaves the same as production, so you can validate your integration's handling of idempotent provisioning before going live. See Deduplication for the full contract.
Deduplication is tenant-scoped. Provisioning the same PAN across different tenants produces separate Network Tokens in each.
Card Art
In the sandbox, the Get a Network Token Account endpoint returns Basis Theory-hosted placeholder images for logo and card_image in place of network-provided assets. The image dimensions, descriptions, and background_color are returned as-is, so you can build and verify your card art rendering before going live. In production, these fields are populated with the card art the network returns for the provisioned card.
Card art availability varies by network. Design your checkout to fall back to a brand logo when
logo, card_image, or background_color are null.Recommended Error Handling
Basis Theory maintains the table below as the canonical customer-facing contract for Network Token provisioning errors. Each error title maps to exactly one detail message. Use the title, rather than the detail text, for programmatic handling, and handle unknown titles without automatically retrying them.
| Error Title | Canonical Detail | Recommended Action | Retry Handling |
|---|---|---|---|
PROVISION_DATA_EXPIRED | The provided card information has expired or changed. | Request updated card details from the user. | After correction |
CARD_VERIFICATION_FAILED | Invalid payment instrument or data associated with the payment instrument. | Use a different card. If a CVV was provided, verify that it is correct. | Do not retry |
CARD_NOT_ELIGIBLE | This card is not eligible for network tokenization by the issuer. | Use a different card. | Do not retry |
CARD_NOT_ALLOWED | Tokenization is currently blocked for this card. | Contact the issuer or use a different card. | Do not retry |
CARD_DECLINED | The card was declined by the issuer during processing. | Contact the issuer or use a different card. | Do not retry |
ISSUER_DECLINED | The card was declined by the issuing bank. | Contact the issuing bank or use a different card. | Do not retry |
PROVISION_NOT_ALLOWED | Tokenization is not allowed for this card or user. | Contact the issuer or use a different card. | Do not retry |
CARD_ELIGIBILITY_ERROR | The card is not eligible for network tokenization. | Use a different card. | Do not retry |
CARD_CANNOT_BE_TOKENIZED | The Card is ineligible for tokenization due to an ongoing issue. | Use a different card. | Do not retry |
CARD_NUMBER_LENGTH_INVALID | The card number does not meet the required length. Please check the card number and try again. | Correct the card number. | After correction |
CARD_DATA_MISSING | Required card data (card number, expiration year, and/or expiration month) is missing. | Add the missing card data. | After correction |
INVALID_PROPERTY | A property validation check has failed. | Correct the invalid property. | After correction |
INVALID_INPUT | Could not find data linked with the provided input. | Verify the referenced input and identifiers. | After correction |
INVALID_FORMAT | A required network tokenization identifier has an invalid format. | Correct the identifier. | After correction |
TOKENIZATION_RESOURCE_NOT_FOUND | A required network tokenization resource could not be found. | Verify the referenced Network Token and contact Basis Theory support if it exists. | After correction |
INVALID_REQUEST | The tokenization service could not validate the request. | Review and correct the request. | After correction |
INVALID_PAN_REFERENCE_FORMAT | The PAN reference format is invalid. | Verify the referenced Network Token. | After correction |
INVALID_PAN_REFERENCE | The requested PAN could not be found. | Verify the referenced Network Token. | After correction |
INVALID_TOKEN_REFERENCE_FORMAT | The token reference format is invalid. | Verify the referenced Network Token. | After correction |
NO_ACTIVE_TOKENS | There are no active (not suspended) Tokens for the given Account PAN and consumer account. | Provision the card again. | Do not retry |
INVALID_PAN_FORMAT | The PAN format is invalid, or other data associated with the PAN was incorrect or entered incorrectly. | Correct the card data. | After correction |
INVALID_PAN | The card number could not be validated for network tokenization. | Verify the card data or use a different card. | After correction |
INVALID_PAN_NETWORK | The PAN network is invalid. | Use a supported card. | Do not retry |
INVALID_PAN_EXPIRY_FORMAT | The PAN expiry format is invalid. | Correct the expiration date. | After correction |
INVALID_PAN_EXPIRY | The PAN expiry is invalid. | Correct the expiration date. | After correction |
INVALID_TOKEN_STATUS | The current token's status doesn't support the requested operation. | Retrieve the current status and retry only after it changes to a compatible state. | After correction |
CARD_EXPIRED | Card expired. | Use an updated or different card. | Do not retry |
CARD_CANCELLED | Card is cancelled. | Use a different card. | Do not retry |
ISSUER_NOT_SUPPORTED | The Issuer of the Card provided does not support provisioning for cards they issue. | Use a card from a supported issuer. | Do not retry |
DUPLICATE_REQUEST | The PAN has already been provisioned to the device or the same request is currently being processed. | If you already hold the Network Token for this card, use it. If you do not — for example, the original response was lost — wait for the in-flight request to finish, then provision the card again once to receive the existing token via deduplication. If that attempt returns DUPLICATE_REQUEST again, the card is already provisioned upstream and repeating the call will not resolve it; stop retrying and contact Basis Theory support. | After correction |
INVALID_TOKEN_REFERENCE | The requested token could not be found. | Verify the Network Token identifier. | After correction |
RESOURCE_NOT_FOUND | The requested resource could not be found. | Verify the referenced resource and contact Basis Theory support if it exists. | After correction |
CARD_MARKET_NOT_SUPPORTED | The market of the Card provided is not supported. | Use a supported card. | Do not retry |
UNAUTHORIZED_OPERATION | The Token Reference ID cannot have its status changed as the token has been deleted. | Retrieve the current status and stop the operation if the token was deleted. | Do not retry |
INVALID_TRID_NETWORK | The TRID is invalid or the specified network is not supported. | Verify the Token Requestor configuration or contact Basis Theory support. | Do not retry |
INVALID_PARAMETER | The request does not have a valid set of parameters required to process it. | Correct the request parameters or card details. | After correction |
VALIDATION_FAILED | One or more card fields failed validation. | Correct the invalid card fields. | After correction |
NETWORK_ERROR | A network error occurred while contacting the card network. The request can be retried. | Retry with backoff. | Automatic retry |
NO_RESPONSE_FROM_ISSUER | The card issuer did not respond in time. The request can be retried. | Retry with backoff. | Automatic retry |
NETWORK_RATE_LIMIT | The card network's rate limit was exceeded. The request can be retried after a short delay. | Wait and retry with backoff. | Automatic retry |
UNEXPECTED_ERROR | An unexpected error occurred during network tokenization. | Contact Basis Theory support if the error persists. | Do not retry |
Retry handling has the following meanings:
- Automatic retry: Retry the same request with exponential backoff and the same idempotency key.
- After correction: Do not retry automatically. Correct the input or state described in the recommended action, then submit the request again.
- Do not retry: Repeating the same request is not expected to succeed. Follow the recommended action instead.
The specific titles in this table can replace
UNEXPECTED_ERROR for conditions that were previously not classified. The response schema and HTTP status remain unchanged. If your integration treats every 422 response as terminal or matches on the detail message, update it to branch on the error title and retry handling above.