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": "Jonh 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": "Jonh 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": "Jonh 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: "Jonh 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: "Jonh 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: "Jonh 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("Jonh 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("Jonh 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("Jonh 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"
                }
            }
        ]
    },
    "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"
                }
            }
        ]
    },
    "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"
}

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 the card data. 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

Both token_id and token_intent_id can be present if a token intent is eventually transformed into a token.

Card Details

Attribute	Type	Description
`bin`	string	Six to eight digit BIN of the card
`last4`	string	Last four digits of the card
`expiration_month`	number	The 2-digit expiration month of the card
`expiration_year`	number	The 4-digit expiration year of the card
`brand`	string	The primary card brand
`funding`	string	The primary funding type of the card
`segment`	string	The segmentation of the card (eg., Consumer, Commercial)
`issuer`	object	Describes the contry 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 card
`additional`	array	Contains additional details associated to the same BIN number. See Card Additional for details.

Card properties shows the primary card details, while Card.additional provides additional card details found for the same BIN.

If a card 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.

Card Additional

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

Issuer

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

Card Brands

The following card brands are supported in the card 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

Authentication Types

Authentication Type	Description
`sca_required`	Indicates that Strong Customer Authentication (SCA) is required (e.g. 3DS)

Cryptogram Object

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

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.

Visa Cards

Test PAN	Response
`4111111111111111`	Success
`4012888888881881`	Provision Data Expired
`4330251207506660`	Card Verification Failed
`4539097887163333`	Card Not Eligible
`4929980395567582`	Card Not Allowed
`4929544240318920`	Card Declined
`4916725297925395`	Provision Not Allowed
`4711358892785746`	Card Eligibility Error

Mastercard Cards

Test PAN	Response
`5555555555554444`	Success
`5105105105105100`	Provision Data Expired
`5461310156953048`	Card Verification Failed
`5325191087030619`	Card Not Eligible
`5580422612666704`	Card Not Allowed
`5157204564548129`	Card Declined
`5336475987107024`	Provision Not Allowed
`5233580618829955`	Card Eligibility Error

Discover Cards

Test PAN	Response
`6011111111111117`	Success
`6011601160116611`	Provision Data Expired
`6011168802268945`	Card Verification Failed
`6011690151507086`	Card Not Eligible
`6011444770992901`	Card Not Allowed
`6011760519541711`	Card Declined
`6011490740263725`	Provision Not Allowed
`6011000990139424`	Card Eligibility Error

American Express Cards

Test PAN	Response
`378282246310005`	Success
`371449635398431`	Provision Data Expired
`370488998077498`	Card Verification Failed
`373555735376156`	Card Not Eligible
`378025849667382`	Card Not Allowed
`348322853530243`	Card Declined
`375155165213132`	Provision Not Allowed
`348835199015504`	Card Eligibility Error

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​

Delete a Network Token​

Permissions​

Request​

Request Parameters​

Response​

Network Token Object​

Card Details​

Card Additional​

Issuer​

Card Brands​

Card Funding Types​

Authentication Types​

Cryptogram Object​

Test Cards​

Visa Cards​

Mastercard Cards​

Discover Cards​

American Express Cards​

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

Delete a Network Token

Permissions

Request

Request Parameters

Response

Network Token Object

Card Details

Card Additional

Issuer

Card Brands

Card Funding Types

Authentication Types

Cryptogram Object

Test Cards

Visa Cards

Mastercard Cards

Discover Cards

American Express Cards