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": "4000000000000002",
"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.basistheory.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.

Both Long and Short cryptograms are available thorugh Basis Theory - reach out if you have any questions
{
"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_yearintegerFour-digit card 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