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

Permissions

network-token:create

Request

cURL
Node
C#
Java
Python

# 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"
        }
      }
    }'

// Using an existing token ID
await client.networkTokens.create({
    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
await client.networkTokens.create({
    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
await client.networkTokens.create({
    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"
      }
    }
  }
);

// Using an existing token ID
await client.NetworkTokens.CreateAsync(
    new CreateNetworkTokenRequest
    {
        TokenId = "c06d0789-0a38-40be-b7cc-c28a718f76f1",
        CardholderInfo = new CardholderInfo
        {
            Name = "John Doe",
            Address = new Address
            {
                Line1 = "123 Main Street",
                Line2 = "Apt 4B",
                Line3 = "Building 7",
                PostalCode = "90210",
                City = "Beverly Hills",
                StateCode = "CA",
                CountryCode = "USA"
            }
        }
    });

// Using an existing token intent ID
await client.NetworkTokens.CreateAsync(
    new CreateNetworkTokenRequest
    {
        TokenIntentId = "c06d0789-0a38-40be-b7cc-c28a718f76f1",
        CardholderInfo = new CardholderInfo
        {
            Name = "John Doe",
            Address = new Address
            {
                Line1 = "123 Main Street",
                Line2 = "Apt 4B",
                Line3 = "Building 7",
                PostalCode = "90210",
                City = "Beverly Hills",
                StateCode = "CA",
                CountryCode = "USA"
            }
        }
    });

// Using raw card data
await client.NetworkTokens.CreateAsync(
    new CreateNetworkTokenRequest
    {
        Data = new Card
        {
            Number = "4111111111111111",
            ExpirationMonth = 03,
            ExpirationYear = 2027,
            Cvc = "123"
        },
        CardholderInfo = new CardholderInfo
        {
            Name = "John Doe",
            Address = new Address
            {
                Line1 = "123 Main Street",
                Line2 = "Apt 4B",
                Line3 = "Building 7",
                PostalCode = "90210",
                City = "Beverly Hills",
                StateCode = "CA",
                CountryCode = "USA"
            }
        }
    });

// Using an existing token ID
NetworkToken networkToken2 = new NetworkTokensClient(ClientOptions.builder().build())
  .create(CreateNetworkTokenRequest.builder()
    .tokenId("c06d0789-0a38-40be-b7cc-c28a718f76f1")
    .cardholderInfo(CardholderInfo.builder()
    .name("John Doe")
    .address(Address.builder()
      .line1("123 Main Street")
      .line2("Apt 4B")
      .line3("Building 7")
      .postalCode("90210")
      .city("Beverly Hills")
      .stateCode("CA")
      .countryCode("USA")
      .build())
    .build())
  .build());

// Using an existing token intent ID
NetworkToken networkToken3 = new NetworkTokensClient(ClientOptions.builder().build())
  .create(CreateNetworkTokenRequest.builder()
    .tokenIntentId("c06d0789-0a38-40be-b7cc-c28a718f76f1")
    .cardholderInfo(CardholderInfo.builder()
    .name("John Doe")
    .address(Address.builder()
      .line1("123 Main Street")
      .line2("Apt 4B")
      .line3("Building 7")
      .postalCode("90210")
      .city("Beverly Hills")
      .stateCode("CA")
      .countryCode("USA")
      .build())
    .build())
  .build());

// Using raw card data
NetworkToken networkToken1 = new NetworkTokensClient(ClientOptions.builder().build())
  .create(CreateNetworkTokenRequest.builder()
    .cardholderInfo(CardholderInfo.builder()
    .name("John Doe")
    .address(Address.builder()
      .line1("123 Main Street")
      .line2("Apt 4B")
      .line3("Building 7")
      .postalCode("90210")
      .city("Beverly Hills")
      .stateCode("CA")
      .countryCode("USA")
      .build())
    .build())
  .data(Card.builder()
    .number("4111111111111111")
    .expirationMonth(3)
    .expirationYear(2027)
    .cvc("123")
    .build())
  .build());

# Using an existing token ID
await client.network_tokens.create(
    token_id="c06d0789-0a38-40be-b7cc-c28a718f76f1",
    cardholder_info=CardholderInfo(
        name="John Doe",
        address=Address(
            line1="123 Main Street",
            line2="Apt 4B",
            line3="Building 7",
            postal_code="90210",
            city="Beverly Hills",
            state_code="CA",
            country_code="US"
        )
    )
)

# Using an existing token intent ID
await client.network_tokens.create(
    token_intent_id="c06d0789-0a38-40be-b7cc-c28a718f76f1",
    cardholder_info=CardholderInfo(
        name="John Doe",
        address=Address(
            line1="123 Main Street",
            line2="Apt 4B",
            line3="Building 7",
            postal_code="90210",
            city="Beverly Hills",
            state_code="CA",
            country_code="US"
        )
    )
)

# Using raw card data
await client.network_tokens.create(
    data=Card(
        number="4111111111111111",
        expiration_month=3,
        expiration_year=2027,
        cvc="123"
    ),
    cardholder_info=CardholderInfo(
        name="John Doe",
        address=Address(
            line1="123 Main Street",
            line2="Apt 4B",
            line3="Building 7",
            postal_code="90210",
            city="Beverly Hills",
            state_code="CA",
            country_code="US"
        )
    )
)

Request Parameters

Attribute	Required	Type	Description
data	No	object	The card data to create a Network Token
token_intent_id	No	string	The ID of a Token Intent to use as source for creating a Network Token
token_id	No	string	The ID of a Token to use as source for creating a Network Token
cardholder_info	No	object	The 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

Attribute	Required	Type	Description
number	Yes	string	The card number to tokenize
expiration_month	Yes	string	The card's expiration month
expiration_year	Yes	string	The card's four-digit expiration year
cvc	No	string	The card's verification code

Cardholder Information

Attribute	Required	Type	Description
name	No	string	The full name of the cardholder
address	No	object	The cardholder address details

Address Details

Attribute	Required	Type	Description
line1	No	string	The first line of the street address
line2	No	string	The second line of the street address
line3	No	string	The third line of the street address
postal_code	No	string	The postal code of the address
city	No	string	The city of the address
state_code	No	string	The state or province code of the address
country_code	No	string	The 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}

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
Node
C#
Java
Python

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

await client.networkTokens.get("485fcc69-e105-4239-b821-92c612f9b03d");

await client.NetworkTokens.GetAsync("485fcc69-e105-4239-b821-92c612f9b03d");

NetworkToken networkToken = new NetworkTokensClient(ClientOptions.builder().build())
  .get("485fcc69-e105-4239-b821-92c612f9b03d");

await client.network_tokens.get("485fcc69-e105-4239-b821-92c612f9b03d")

Request Parameters

Attribute	Required	Type	Description
id	Yes	string	The 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

Permissions

network-token:cryptogram

Request

cURL
Node
C#
Java
Python

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'

await client.networkTokens.cryptogram("2c1577f3-6c1b-4575-9488-13202405fefe");

await client.NetworkTokens.CryptogramAsync("2c1577f3-6c1b-4575-9488-13202405fefe");

NetworkTokenCryptogram cryptogram = new NetworkTokensClient(ClientOptions.builder().build())
  .cryptogram("2c1577f3-6c1b-4575-9488-13202405fefe");

await client.network_tokens.cryptogram("2c1577f3-6c1b-4575-9488-13202405fefe")

Request Parameters

Attribute	Required	Type	Description
id	Yes	string	The 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

Permissions

network-token:suspend

Request

cURL
Node
C#
Java
Python

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'

await client.networkTokens.suspend("485fcc69-e105-4239-b821-92c612f9b03d");

await client.NetworkTokens.SuspendAsync("485fcc69-e105-4239-b821-92c612f9b03d");

new NetworkTokensClient(ClientOptions.builder().build())
  .suspend("485fcc69-e105-4239-b821-92c612f9b03d");

await client.network_tokens.suspend("485fcc69-e105-4239-b821-92c612f9b03d")

Request Parameters

Attribute	Required	Type	Description
id	Yes	string	The 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

Permissions

network-token:resume

Request

cURL
Node
C#
Java
Python

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'

await client.networkTokens.resume("485fcc69-e105-4239-b821-92c612f9b03d");

await client.NetworkTokens.ResumeAsync("485fcc69-e105-4239-b821-92c612f9b03d");

new NetworkTokensClient(ClientOptions.builder().build())
  .resume("485fcc69-e105-4239-b821-92c612f9b03d");

await client.network_tokens.resume("485fcc69-e105-4239-b821-92c612f9b03d")

Request Parameters

Attribute	Required	Type	Description
id	Yes	string	The 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}

Permissions

network-token:delete

Request

cURL
Node
C#
Java
Python

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'

await client.networkTokens.delete("485fcc69-e105-4239-b821-92c612f9b03d");

await client.NetworkTokens.DeleteAsync("485fcc69-e105-4239-b821-92c612f9b03d");

new NetworkTokensClient(ClientOptions.builder().build())
  .delete("485fcc69-e105-4239-b821-92c612f9b03d");

await client.network_tokens.delete("485fcc69-e105-4239-b821-92c612f9b03d")

Request Parameters

Attribute	Required	Type	Description
id	Yes	string	The 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

Attribute	Type	Description
`id`	string	Unique identifier of the network token
`tenant_id`	uuid	The tenant ID associated with the network token
`data.number`	string	Masked card number
`data.expiration_month`	integer	Card's expiration month
`data.expiration_year`	integer	Card's expiration year
`network_token`	object	An object containing details for the network token data. See Network Token Details for more information.
`card`	object	An object containing details for the original card data used to create the network token. See Card Details for more information.
`status`	string	The status of the network token. Possible values: `active`, `inactive` or `suspended`
`created_by`	uuid	ID of the entity that created the network token
`created_at`	date	Timestamp of when the network token was created
`token_id`	uuid	The ID of the token if created using a token_id
`token_intent_id`	uuid	The ID of the token intent if created using a token_intent_id
`par`	string	The Payment Account Reference (PAR) associated with the network token. This is a unique identifier for the payment account.
`_extras`	object	Parent 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

Attribute	Type	Description
`bin`	string	Six to eight digit BIN of the network token
`last4`	string	Last four digits of the network token
`expiration_month`	number	The 2-digit expiration month of the network token
`expiration_year`	number	The 4-digit expiration year of the network token
`brand`	string	The primary card brand
`funding`	string	The primary funding type of the network token
`segment`	string	The segmentation of the network token (eg., Consumer, Commercial)
`issuer`	object	Describes the country and issuing bank. See Issuer for details
`issuer_country`	object
.alpha2	string	Issuing country ISO3166 alpha country code
.numeric	string	Issuing country ISO3166 numeric country code
.name	string	Issuing country name
`authentication`	string	The authentication type required for this network token
`additional`	array	Contains 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

Attribute	Type	Description
`brand`	string	An additional card brand
`funding`	string	An additional funding type of the network token
`authentication`	string	An additional authentication type required for this network token
`issuer`	object	Describes the country and issuing bank. See Issuer for details

Authentication Types

Authentication Type	Description
`sca_required`	Indicates 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.

Brand	Description
`american-express`	American Express
`diners-club`	Diners Club
`discover`	Discover
`ebt`	EBT
`elo`	Elo
`hipercard`	Hipercard
`jcb`	JCB
`mastercard`	Mastercard
`mir`	MIR
`private-label`	Private Label
`proprietary`	Proprietary
`unionpay`	UnionPay
`visa`	Visa

Card Funding Types

Funding Type	Description
`credit`	Credit Card
`debit`	Debit Card
`prepaid`	Prepaid Card

Issuer

Attribute	Type	Description
`country`	string	Issuing country ISO3166 alpha country code
`name`	string	Issuing bank name

Card Details

Attribute	Type	Description
`last4`	string	Last four digits of the original card
`expiration_month`	number	The 1 or 2 digit expiration month of the original card
`expiration_year`	number	The 4-digit expiration year of the original card

Cryptogram Object

Attribute	Type	Description
`cryptogram`	string	The cryptogram generated for the network token
`eci`	string	The ECI value associated with the cryptogram

Extras Object

Attribute	Type	Description
`deduplicated`	boolean	Indicates 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.

Recommended Actions for Test Card Errors

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

Error Title	Recommended Action	Retryable
PROVISION_DATA_EXPIRED	Request updated card details from the user.	✅ Yes
CARD_VERIFICATION_FAILED	Prompt user to re-enter CVV or use another card.	✅ Yes
CARD_NOT_ELIGIBLE	Advise user to use a different card.	❌ No
CARD_NOT_ALLOWED	Advise user to use a different card.	❌ No
CARD_DECLINED	Suggest user contact issuer or try another card.	❌ No
PROVISION_NOT_ALLOWED	Advise user to contact issuer or use another card.	❌ No
CARD_ELIGIBILITY_ERROR	Retry 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 PAN	Response	Error Title
`4111111111111111`	Success	[Not Applicable]
`4012888888881881`	Provision Data Expired	PROVISION_DATA_EXPIRED
`4330251207506660`	Card Verification Failed	CARD_VERIFICATION_FAILED
`4539097887163333`	Card Not Eligible	CARD_NOT_ELIGIBLE
`4929980395567582`	Card Not Allowed	CARD_NOT_ALLOWED
`4929544240318920`	Card Declined	CARD_DECLINED
`4916725297925395`	Provision Not Allowed	PROVISION_NOT_ALLOWED
`4711358892785746`	Card Eligibility Error	CARD_ELIGIBILITY_ERROR

Mastercard Cards

Test PAN	Response	Error Title
`5555555555554444`	Success	[Not Applicable]
`5105105105105100`	Provision Data Expired	PROVISION_DATA_EXPIRED
`5461310156953048`	Card Verification Failed	CARD_VERIFICATION_FAILED
`5325191087030619`	Card Not Eligible	CARD_NOT_ELIGIBLE
`5580422612666704`	Card Not Allowed	CARD_NOT_ALLOWED
`5157204564548129`	Card Declined	CARD_DECLINED
`5336475987107024`	Provision Not Allowed	PROVISION_NOT_ALLOWED
`5233580618829955`	Card Eligibility Error	CARD_ELIGIBILITY_ERROR

Discover Cards

Test PAN	Response	Error Title
`6011111111111117`	Success	[Not Applicable]
`6011601160116611`	Provision Data Expired	PROVISION_DATA_EXPIRED
`6011168802268945`	Card Verification Failed	CARD_VERIFICATION_FAILED
`6011690151507086`	Card Not Eligible	CARD_NOT_ELIGIBLE
`6011444770992901`	Card Not Allowed	CARD_NOT_ALLOWED
`6011760519541711`	Card Declined	CARD_DECLINED
`6011490740263725`	Provision Not Allowed	PROVISION_NOT_ALLOWED
`6011000990139424`	Card Eligibility Error	CARD_ELIGIBILITY_ERROR

American Express Cards

Test PAN	Response	Error Title
`378282246310005`	Success	[Not Applicable]
`371449635398431`	Provision Data Expired	PROVISION_DATA_EXPIRED
`370488998077498`	Card Verification Failed	CARD_VERIFICATION_FAILED
`373555735376156`	Card Not Eligible	CARD_NOT_ELIGIBLE
`378025849667382`	Card Not Allowed	CARD_NOT_ALLOWED
`348322853530243`	Card Declined	CARD_DECLINED
`375155165213132`	Provision Not Allowed	PROVISION_NOT_ALLOWED
`348835199015504`	Card Eligibility Error	CARD_ELIGIBILITY_ERROR

Additional Error Codes

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

Error Title	Description	Recommended Action
CARD_NUMBER_LENGTH_INVALID	The card number does not meet the required length.	Verify the card number length is between 13 and 16 digits inclusive.
CARD_DATA_MISSING	Required 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.

Create a Network Token​

Permissions​

Request​

Request Parameters​

Card Data Object​

Cardholder Information​

Address Details​

Response​

Get a network token​

Permissions​

Request​

Request Parameters​

Response​

Generate a Cryptogram​

Permissions​

Request​

Request Parameters​

Response​

Suspend a Network Token​

Permissions​

Request​

Request Parameters​

Response​

Resume a Network Token​

Permissions​

Request​

Request Parameters​

Response​

Delete a Network Token​

Permissions​

Request​

Request Parameters​

Response​

Network Token Object​

Network Token Details​

Network Token Additional​

Authentication Types​

Card Brands​

Card Funding Types​

Issuer​

Card Details​

Cryptogram Object​

Extras Object​

Test Cards​

Recommended Actions for Test Card Errors​

Error Handling and Retries​

Visa Cards​

Mastercard Cards​

Discover Cards​

American Express Cards​

Additional Error Codes​

Create a Network Token

Permissions

Request

Request Parameters

Card Data Object

Cardholder Information

Address Details

Response

Get a network token

Permissions

Request

Request Parameters

Response

Generate a Cryptogram

Permissions

Request

Request Parameters

Response

Suspend a Network Token

Permissions

Request

Request Parameters

Response

Resume a Network Token

Permissions

Request

Request Parameters

Response

Delete a Network Token

Permissions

Request

Request Parameters

Response

Network Token Object

Network Token Details

Network Token Additional

Authentication Types

Card Brands

Card Funding Types

Issuer

Card Details

Cryptogram Object

Extras Object

Test Cards

Recommended Actions for Test Card Errors

Error Handling and Retries

Visa Cards

Mastercard Cards

Discover Cards

American Express Cards

Additional Error Codes