Skip to main content

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.

Test Cards​

The following test cards can be used to test different error and success scenarios when creating network tokens.

PANCard BrandResponseError Title
4000000000000002VisaSuccess[Not Applicable]
4000000000000085VisaSuccess[Not Applicable]
4000000000000093VisaSuccess[Not Applicable]
5100000000000008MastercardSuccess[Not Applicable]
5100000000000065MastercardSuccess[Not Applicable]
5100000000000073MastercardSuccess[Not Applicable]
6011000000000004DiscoverSuccess[Not Applicable]
370000000000002American ExpressSuccess[Not Applicable]
370000000000069American ExpressSuccess[Not Applicable]
370000000000077American ExpressSuccess[Not Applicable]
4012888888881881VisaProvision Data ExpiredPROVISION_DATA_EXPIRED
5105105105105100MastercardProvision Data ExpiredPROVISION_DATA_EXPIRED
6011601160116611DiscoverProvision Data ExpiredPROVISION_DATA_EXPIRED
371449635398431American ExpressProvision Data ExpiredPROVISION_DATA_EXPIRED
4330251207506660VisaCard Verification FailedCARD_VERIFICATION_FAILED
5461310156953048MastercardCard Verification FailedCARD_VERIFICATION_FAILED
6011168802268945DiscoverCard Verification FailedCARD_VERIFICATION_FAILED
370488998077498American ExpressCard Verification FailedCARD_VERIFICATION_FAILED
4539097887163333VisaCard Not EligibleCARD_NOT_ELIGIBLE
5325191087030619MastercardCard Not EligibleCARD_NOT_ELIGIBLE
6011690151507086DiscoverCard Not EligibleCARD_NOT_ELIGIBLE
373555735376156American ExpressCard Not EligibleCARD_NOT_ELIGIBLE
4929980395567582VisaCard Not AllowedCARD_NOT_ALLOWED
5580422612666704MastercardCard Not AllowedCARD_NOT_ALLOWED
6011444770992901DiscoverCard Not AllowedCARD_NOT_ALLOWED
378025849667382American ExpressCard Not AllowedCARD_NOT_ALLOWED
4929544240318920VisaCard DeclinedCARD_DECLINED
5157204564548129MastercardCard DeclinedCARD_DECLINED
6011760519541711DiscoverCard DeclinedCARD_DECLINED
348322853530243American ExpressCard DeclinedCARD_DECLINED
4916725297925395VisaProvision Not AllowedPROVISION_NOT_ALLOWED
5336475987107024MastercardProvision Not AllowedPROVISION_NOT_ALLOWED
6011490740263725DiscoverProvision Not AllowedPROVISION_NOT_ALLOWED
375155165213132American ExpressProvision Not AllowedPROVISION_NOT_ALLOWED
4711358892785746VisaCard Eligibility ErrorCARD_ELIGIBILITY_ERROR
5233580618829955MastercardCard Eligibility ErrorCARD_ELIGIBILITY_ERROR
6011000990139424DiscoverCard Eligibility ErrorCARD_ELIGIBILITY_ERROR
348835199015504American ExpressCard Eligibility ErrorCARD_ELIGIBILITY_ERROR
5555555555554444MastercardIssuer DeclinedISSUER_DECLINED
These cards are not valid for real transactions and should only be used in the Basis Theory sandbox environment.

Deduplication​

When the same PAN is provisioned more than once within a sandbox tenant, the API returns the existing Network Token with _extras.deduplicated: true. You can use this to validate your integration's handling of idempotent provisioning before going live. In production, deduplication behavior varies by network — see Deduplication for details.

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.

Depending on the error you receive, you should take different actions. This table provides guidance on handling each error type:

Error TitleRecommended ActionRetryable
PROVISION_DATA_EXPIREDRequest updated card details from the user.✅ Yes
CARD_VERIFICATION_FAILEDPrompt user to re-enter CVV or use another card.✅ Yes
CARD_NOT_ELIGIBLEAdvise user to use a different card.❌ No
CARD_NOT_ALLOWEDAdvise user to use a different card.❌ No
CARD_DECLINEDSuggest user contact issuer or try another card.❌ No
ISSUER_DECLINEDSuggest user contact their issuing bank or try another card.❌ No
PROVISION_NOT_ALLOWEDAdvise user to contact issuer or use another card.❌ No
CARD_NUMBER_LENGTH_INVALIDVerify the card number length is between 13 and 16 digits inclusive.❌ No
CARD_DATA_MISSINGEnsure at least card number, expiration year, and expiration month are provided in the entity.❌ No
CARD_ELIGIBILITY_ERRORRetry once; if unsuccessful, use a different card.⚠️ Once

Not all errors can be safely retried without user interaction. The retry statuses are defined as:

  • ✅ Yes: You can safely retry the request after collecting updated or corrected user information.
  • ⚠️ Once: Attempt one retry; further retries might not resolve the issue.
  • ❌ No: Do not retry automatically. The user must provide alternative card information or contact the issuer.
Last updated on