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

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

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"
      }
    }
  }
);

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"
            }
        }
    });

NetworkToken networkToken = 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());

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	Yes	object	Card details required to generate a network token
data.number	Yes	string	The card number to tokenize
data.expiration_month	Yes	string	The card's expiration month
data.expiration_year	Yes	string	The card's four-digit expiration year
data.cvc	Yes	string	The card's verification code
cardholder_info	Yes	object	The cardholder information

Cardholder Information

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

Address Details

Attribute	Required	Type	Description
line1	Yes	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	Yes	string	The postal code of the address
city	Yes	string	The city of the address
state_code	No	string	The state or province code of the address
country_code	Yes	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"
}

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.
`created_by`	uuid	ID of the entity that created the network token
`created_at`	date	Timestamp of when the network token was created

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

Create a Network Token​

Permissions​

Request​

Request Parameters​

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​

Create a Network Token

Permissions

Request

Request Parameters

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