Skip to main content

Network Tokens

Network Tokens enables merchants to convert raw card details into secure, network-issued tokens. The network token endpoints support one-time purchases, card-on-file transactions, subscriptions and other recurring or cross-border payments by issuing tokens that automatically update on card reissues and boost authorization rates—all without ever storing PANs.

Create a Network Token

Creates a Network Token.

POST
https://api.basistheory.com/network-tokens
Copy

Permissions

network-token:create

Request

# Using an existing token ID
curl -L 'https://api.basistheory.com/network-tokens' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"token_id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
"cardholder_info": {
"name": "John Doe",
"address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"line3": "Building 7",
"postal_code": "90210",
"city": "Beverly Hills",
"state_code": "CA",
"country_code": "USA"
}
}
}'

# Using an existing token intent ID
curl -L 'https://api.basistheory.com/network-tokens' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"token_intent_id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
"cardholder_info": {
"name": "John Doe",
"address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"line3": "Building 7",
"postal_code": "90210",
"city": "Beverly Hills",
"state_code": "CA",
"country_code": "USA"
}
}
}'

# Using raw card data
curl -L 'https://api.basistheory.com/network-tokens' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"data": {
"number": "4111111111111111",
"expiration_month": "03",
"expiration_year": "2027",
"cvc": "123"
},
"cardholder_info": {
"name": "John Doe",
"address": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"line3": "Building 7",
"postal_code": "90210",
"city": "Beverly Hills",
"state_code": "CA",
"country_code": "USA"
}
}
}'

Request Parameters

AttributeRequiredTypeDescription
dataNoobjectThe card data to create a Network Token
token_intent_idNostringThe ID of a Token Intent to use as source for creating a Network Token
token_idNostringThe ID of a Token to use as source for creating a Network Token
cardholder_infoNoobjectThe cardholder information
Exactly one of the following is required: data, token_intent_id or token_id when creating a Network Token.
When using the data object with raw card details, your system must be PCI DSS compliant. Consider using token_id or token_intent_id instead to reduce compliance scope.
When using a Token ID or Token Intent ID, the record must be a card token containing at least number, expiration_month and expiration_year attributes.

Card Data Object

AttributeRequiredTypeDescription
numberYesstringThe card number to tokenize
expiration_monthYesstringThe card's expiration month
expiration_yearYesstringThe card's four-digit expiration year
cvcNostringThe card's verification code

Cardholder Information

AttributeRequiredTypeDescription
nameNostringThe full name of the cardholder
addressNoobjectThe cardholder address details

Address Details

AttributeRequiredTypeDescription
line1NostringThe first line of the street address
line2NostringThe second line of the street address
line3NostringThe third line of the street address
postal_codeNostringThe postal code of the address
cityNostringThe city of the address
state_codeNostringThe state or province code of the address
country_codeNostringThe country code of the address

Response

Returns a network token object if successful. Returns an error if there were validation errors, or the network token failed to create.

{
"id": "1a97a7f6-5d7e-4a8e-ad08-c2472cfedf7f",
"tenant_id": "a4ed655d-325e-4490-8c5a-2ff288db7aa5",
"data": {
"number": "XXXXXXXXXXXX2426",
"expiration_month": 12,
"expiration_year": 2029
},
"network_token": {
"bin": "433561",
"last4": "2426",
"expiration_month": 12,
"expiration_year": 2029,
"brand": "visa",
"funding": "debit",
"issuer": {
"country": "US",
"name": "CENTRAL FEDERAL SAVINGS AND LOAN ASSOCIATION"
},
"issuer_country": {
"alpha2": "US",
"name": "UNITED STATES OF AMERICA",
"numeric": "840"
},
"segment": "Consumer",
"additional": [
{
"brand": "star",
"funding": "debit",
"issuer": {
"country": "US"
}
}
]
},
"card": {
"last4": "8783",
"expiration_month": 10,
"expiration_year": 2025
},
"par": "50024568e5147564f4154c4c2f4g7",
"status": "active",
"created_by": "f8dee6b4-2f92-4052-81f9-8b0fc8078a6e",
"created_at": "2025-05-07T17:04:06.3338559+00:00",
"token_id": "c06d0789-0a38-40be-b7cc-c28a718f76f1", // If network token was created using a token_id
"token_intent_id": "c06d0789-0a38-40be-b7cc-c28a718f76f1" // If network token was created using a token_intent_id
}

Get a network token

Retrieves a Network Token.

GET
https://api.basistheory.com/network-tokens/{id}
Copy

Permissions

network-token:read network-token:reveal

At least one of these permissions is required to access the information. The network-token:read permission displays the card number in data.number with a masked format (showing only the last 4 digits), while the network-token:reveal permission provides access to view the complete unmasked card number.

If both permissions are set, the network-token:reveal permission will take precedence and display the complete unmasked card number.

Request

curl -L 'https://api.basistheory.com/network-tokens/485fcc69-e105-4239-b821-92c612f9b03d' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json'

Request Parameters

AttributeRequiredTypeDescription
idYesstringThe ID of the network token to retrieve

Response

Returns a network token object if successful. Returns an error if there were validation errors, or the network token failed to retrieve.

{
"id": "1a97a7f6-5d7e-4a8e-ad08-c2472cfedf7f",
"tenant_id": "a4ed655d-325e-4490-8c5a-2ff288db7aa5",
"data": {
"number": "XXXXXXXXXXXX2426",
"expiration_month": 12,
"expiration_year": 2029
},
"network_token": {
"bin": "433561",
"last4": "2426",
"expiration_month": 12,
"expiration_year": 2029,
"brand": "visa",
"funding": "debit",
"issuer": {
"country": "US",
"name": "CENTRAL FEDERAL SAVINGS AND LOAN ASSOCIATION"
},
"issuer_country": {
"alpha2": "US",
"name": "UNITED STATES OF AMERICA",
"numeric": "840"
},
"segment": "Consumer",
"additional": [
{
"brand": "star",
"funding": "debit",
"issuer": {
"country": "US"
}
}
]
},
"par": "50024568e5147564f4154c4c2f4g7",
"status": "active",
"created_by": "f8dee6b4-2f92-4052-81f9-8b0fc8078a6e",
"created_at": "2025-05-07T17:04:06.3338559+00:00"
}

Generate a Cryptogram

Generate a cryptogram for a network token.

POST
https://api.basistheory.com/network-tokens/{id}/cryptogram
Copy

Permissions

network-token:cryptogram

Request

curl -L -X POST 'https://api.flock-dev.com/network-tokens/2c1577f3-6c1b-4575-9488-13202405fefe/cryptogram' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json'

Request Parameters

AttributeRequiredTypeDescription
idYesstringThe ID of the network token to create cryptogram

Response

Returns a cryptogram object if successful. Returns an error if there were validation errors, or the cryptogram failed to create.

{
"cryptogram": "2z8pd6WGPUi/BBesvjJcyw==",
"eci": "07"
}

Suspend a Network Token

Suspends a Network Token, preventing it from being used for future transactions.

PUT
https://api.basistheory.com/network-tokens/{id}/suspend
Copy

Permissions

network-token:suspend

Request

curl -L -X PUT 'https://api.basistheory.com/network-tokens/485fcc69-e105-4239-b821-92c612f9b03d/suspend' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json'

Request Parameters

AttributeRequiredTypeDescription
idYesstringThe ID of the network token to suspend

Response

Returns a network token object if successful. Returns an error if there were validation errors, or the network token failed to suspend.

{
"id": "1a97a7f6-5d7e-4a8e-ad08-c2472cfedf7f",
"tenant_id": "a4ed655d-325e-4490-8c5a-2ff288db7aa5",
"data": {
"number": "XXXXXXXXXXXX2426",
"expiration_month": 12,
"expiration_year": 2029
},
"network_token": {
"bin": "433561",
"last4": "2426",
"expiration_month": 12,
"expiration_year": 2029,
"brand": "visa",
"funding": "debit",
"issuer": {
"country": "US",
"name": "CENTRAL FEDERAL SAVINGS AND LOAN ASSOCIATION"
},
"issuer_country": {
"alpha2": "US",
"name": "UNITED STATES OF AMERICA",
"numeric": "840"
},
"segment": "Consumer",
"additional": [
{
"brand": "star",
"funding": "debit",
"issuer": {
"country": "US"
}
}
]
},
"par": "50024568e5147564f4154c4c2f4g7",
"status": "suspended",
"created_by": "f8dee6b4-2f92-4052-81f9-8b0fc8078a6e",
"created_at": "2025-05-07T17:04:06.3338559+00:00"
}

Resume a Network Token

Resumes a suspended Network Token, allowing it to be used again for future transactions.

PUT
https://api.basistheory.com/network-tokens/{id}/resume
Copy

Permissions

network-token:resume

Request

curl -L -X PUT 'https://api.basistheory.com/network-tokens/485fcc69-e105-4239-b821-92c612f9b03d/resume' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json'

Request Parameters

AttributeRequiredTypeDescription
idYesstringThe ID of the network token to resume

Response

Returns a network token object if successful. Returns an error if there were validation errors, or the network token failed to activate.

{
"id": "1a97a7f6-5d7e-4a8e-ad08-c2472cfedf7f",
"tenant_id": "a4ed655d-325e-4490-8c5a-2ff288db7aa5",
"data": {
"number": "XXXXXXXXXXXX2426",
"expiration_month": 12,
"expiration_year": 2029
},
"network_token": {
"bin": "433561",
"last4": "2426",
"expiration_month": 12,
"expiration_year": 2029,
"brand": "visa",
"funding": "debit",
"issuer": {
"country": "US",
"name": "CENTRAL FEDERAL SAVINGS AND LOAN ASSOCIATION"
},
"issuer_country": {
"alpha2": "US",
"name": "UNITED STATES OF AMERICA",
"numeric": "840"
},
"segment": "Consumer",
"additional": [
{
"brand": "star",
"funding": "debit",
"issuer": {
"country": "US"
}
}
]
},
"par": "50024568e5147564f4154c4c2f4g7",
"status": "active",
"created_by": "f8dee6b4-2f92-4052-81f9-8b0fc8078a6e",
"created_at": "2025-05-07T17:04:06.3338559+00:00"
}

Delete a Network Token

Deletes a Network Token.

DELETE
https://api.basistheory.com/network-tokens/{id}
Copy

Permissions

network-token:delete

Request

curl -L -X DELETE 'https://api.basistheory.com/network-tokens/485fcc69-e105-4239-b821-92c612f9b03d' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'Content-Type: application/json'

Request Parameters

AttributeRequiredTypeDescription
idYesstringThe ID of the network token to delete

Response

Returns a 204 No Content response if successful. Returns an error if there were validation errors, or the network token failed to delete.

Network Token Object

AttributeTypeDescription
idstringUnique identifier of the network token
tenant_iduuidThe tenant ID associated with the network token
data.numberstringMasked card number
data.expiration_monthintegerCard's expiration month
data.expiration_yearintegerCard's expiration year
network_tokenobjectAn object containing details for the network token data. See Network Token Details for more information.
cardobjectAn object containing details for the original card data used to create the network token. See Card Details for more information.
statusstringThe status of the network token. Possible values: active, inactive or suspended
created_byuuidID of the entity that created the network token
created_atdateTimestamp of when the network token was created
token_iduuidThe ID of the token if created using a token_id
token_intent_iduuidThe ID of the token intent if created using a token_intent_id
parstringThe Payment Account Reference (PAR) associated with the network token. This is a unique identifier for the payment account.
_extrasobjectParent object containing additional details. See Extras Object for more information.
Both token_id and token_intent_id can be present if a token intent is eventually transformed into a token.

Network Token Details

AttributeTypeDescription
binstringSix to eight digit BIN of the network token
last4stringLast four digits of the network token
expiration_monthnumberThe 2-digit expiration month of the network token
expiration_yearnumberThe 4-digit expiration year of the network token
brandstringThe primary card brand
fundingstringThe primary funding type of the network token
segmentstringThe segmentation of the network token (eg., Consumer, Commercial)
issuerobjectDescribes the country and issuing bank. See Issuer for details
issuer_countryobject
 .alpha2stringIssuing country ISO3166 alpha country code
 .numericstringIssuing country ISO3166 numeric country code
 .namestringIssuing country name
authenticationstringThe authentication type required for this network token
additionalarrayContains additional details associated to the same BIN number. See Card Additional for details.
Network token properties shows the primary card details, while Card.additional provides additional network token details found for the same BIN.
If a network token number does not correspond to any known BIN Details, then brand, funding, issuer_country, and authentication will default to null and the default BIN will be returned.

Network Token Additional

AttributeTypeDescription
brandstringAn additional card brand
fundingstringAn additional funding type of the network token
authenticationstringAn additional authentication type required for this network token
issuerobjectDescribes the country and issuing bank. See Issuer for details

Authentication Types

Authentication TypeDescription
sca_requiredIndicates that Strong Customer Authentication (SCA) is required (e.g. 3DS)

Card Brands

The following card brands are supported in the network token property (primary details). Please note that the additional property may contain extra card brands not listed in this table.
BrandDescription
american-expressAmerican Express
diners-clubDiners Club
discoverDiscover
ebtEBT
eloElo
hipercardHipercard
jcbJCB
mastercardMastercard
mirMIR
private-labelPrivate Label
proprietaryProprietary
unionpayUnionPay
visaVisa

Card Funding Types

Funding TypeDescription
creditCredit Card
debitDebit Card
prepaidPrepaid Card

Issuer

AttributeTypeDescription
countrystringIssuing country ISO3166 alpha country code
namestringIssuing bank name

Card Details

AttributeTypeDescription
last4stringLast four digits of the original card
expiration_monthnumberThe 1 or 2 digit expiration month of the original card
expiration_yearnumberThe 4-digit expiration year of the original card

Cryptogram Object

AttributeTypeDescription
cryptogramstringThe cryptogram generated for the network token
ecistringThe ECI value associated with the cryptogram

Extras Object

AttributeTypeDescription
deduplicatedbooleanIndicates if this network token is a duplicate of a pre-existing one. When true, the response will contain the existing network token details rather than creating a new one

Test Cards

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

These cards are not valid for real transactions and should only be used in the Basis Theory sandbox environment.

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
PROVISION_NOT_ALLOWEDAdvise user to contact issuer or use another card.No
CARD_ELIGIBILITY_ERRORRetry once; if unsuccessful, use a different card.⚠️ Once

Error Handling and Retries

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.

Visa Cards

Test PANResponseError Title
4111111111111111Success[Not Applicable]
4012888888881881Provision Data ExpiredPROVISION_DATA_EXPIRED
4330251207506660Card Verification FailedCARD_VERIFICATION_FAILED
4539097887163333Card Not EligibleCARD_NOT_ELIGIBLE
4929980395567582Card Not AllowedCARD_NOT_ALLOWED
4929544240318920Card DeclinedCARD_DECLINED
4916725297925395Provision Not AllowedPROVISION_NOT_ALLOWED
4711358892785746Card Eligibility ErrorCARD_ELIGIBILITY_ERROR

Mastercard Cards

Test PANResponseError Title
5555555555554444Success[Not Applicable]
5105105105105100Provision Data ExpiredPROVISION_DATA_EXPIRED
5461310156953048Card Verification FailedCARD_VERIFICATION_FAILED
5325191087030619Card Not EligibleCARD_NOT_ELIGIBLE
5580422612666704Card Not AllowedCARD_NOT_ALLOWED
5157204564548129Card DeclinedCARD_DECLINED
5336475987107024Provision Not AllowedPROVISION_NOT_ALLOWED
5233580618829955Card Eligibility ErrorCARD_ELIGIBILITY_ERROR

Discover Cards

Test PANResponseError Title
6011111111111117Success[Not Applicable]
6011601160116611Provision Data ExpiredPROVISION_DATA_EXPIRED
6011168802268945Card Verification FailedCARD_VERIFICATION_FAILED
6011690151507086Card Not EligibleCARD_NOT_ELIGIBLE
6011444770992901Card Not AllowedCARD_NOT_ALLOWED
6011760519541711Card DeclinedCARD_DECLINED
6011490740263725Provision Not AllowedPROVISION_NOT_ALLOWED
6011000990139424Card Eligibility ErrorCARD_ELIGIBILITY_ERROR

American Express Cards

Test PANResponseError Title
378282246310005Success[Not Applicable]
371449635398431Provision Data ExpiredPROVISION_DATA_EXPIRED
370488998077498Card Verification FailedCARD_VERIFICATION_FAILED
373555735376156Card Not EligibleCARD_NOT_ELIGIBLE
378025849667382Card Not AllowedCARD_NOT_ALLOWED
348322853530243Card DeclinedCARD_DECLINED
375155165213132Provision Not AllowedPROVISION_NOT_ALLOWED
348835199015504Card Eligibility ErrorCARD_ELIGIBILITY_ERROR

Additional Error Codes

When transforming a Token or Token Intent into a Network Token, you may encounter these additional error codes:

Error TitleDescriptionRecommended Action
CARD_NUMBER_LENGTH_INVALIDThe card number does not meet the required length.Verify the card number length is between 13 and 16 digits inclusive.
CARD_DATA_MISSINGRequired card data (card number, expiration year, and/or expiration month) is missing.Ensure at least card number, expiration year, and expiration month are provided in the entity.