Network Tokens

Network Token operations support Merchant Context: requests that include a BT-MERCHANT-ID header act as that tenant merchant and only see its Network Tokens. Requests without the header operate at the tenant level.

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 ID with an expiration date override
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",
      "expiration_month": 10,
      "expiration_year": 2025
    }'

# 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 an existing token intent ID with an expiration date override
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",
      "expiration_month": 10,
      "expiration_year": 2025
    }'

# 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": 3,
        "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({
    tokenId: "c06d0789-0a38-40be-b7cc-c28a718f76f1",
    cardholderInfo: {
      name: "John Doe",
      address: {
        line1: "123 Main Street",
        line2: "Apt 4B",
        line3: "Building 7",
        city: "Beverly Hills",
        postalCode: "90210",
        stateCode: "CA",
        countryCode: "USA"
      }
    }
  }
);

// Using an existing token ID with an expiration date override
await client.networkTokens.create({
    tokenId: "c06d0789-0a38-40be-b7cc-c28a718f76f1",
    expirationMonth: 10,
    expirationYear: 2025
  }
);

// Using an existing token intent ID
await client.networkTokens.create({
    tokenIntentId: "c06d0789-0a38-40be-b7cc-c28a718f76f1",
    cardholderInfo: {
      name: "John Doe",
      address: {
        line1: "123 Main Street",
        line2: "Apt 4B",
        line3: "Building 7",
        city: "Beverly Hills",
        postalCode: "90210",
        stateCode: "CA",
        countryCode: "USA"
      }
    }
  }
);

// Using an existing token intent ID with an expiration date override
await client.networkTokens.create({
    tokenIntentId: "c06d0789-0a38-40be-b7cc-c28a718f76f1",
    expirationMonth: 10,
    expirationYear: 2025
  }
);

// Using raw card data
await client.networkTokens.create({
    data: {
      number: "4000000000000002",
      expirationMonth: 3,
      expirationYear: 2027,
      cvc: "123"
    },
    cardholderInfo: {
      name: "John Doe",
      address: {
        line1: "123 Main Street",
        line2: "Apt 4B",
        line3: "Building 7",
        city: "Beverly Hills",
        postalCode: "90210",
        stateCode: "CA",
        countryCode: "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 ID with an expiration date override
await client.NetworkTokens.CreateAsync(
    new CreateNetworkTokenRequest
    {
        TokenId = "c06d0789-0a38-40be-b7cc-c28a718f76f1",
        ExpirationMonth = 10,
        ExpirationYear = 2025
    });

// 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 an existing token intent ID with an expiration date override
await client.NetworkTokens.CreateAsync(
    new CreateNetworkTokenRequest
    {
        TokenIntentId = "c06d0789-0a38-40be-b7cc-c28a718f76f1",
        ExpirationMonth = 10,
        ExpirationYear = 2025
    });

// Using raw card data
await client.NetworkTokens.CreateAsync(
    new CreateNetworkTokenRequest
    {
        Data = new Card
        {
            Number = "4000000000000002",
            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 ID with an expiration date override
NetworkToken networkToken4 = new NetworkTokensClient(ClientOptions.builder().build())
  .create(CreateNetworkTokenRequest.builder()
    .tokenId("c06d0789-0a38-40be-b7cc-c28a718f76f1")
    .expirationMonth(10)
    .expirationYear(2025)
  .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 an existing token intent ID with an expiration date override
NetworkToken networkToken5 = new NetworkTokensClient(ClientOptions.builder().build())
  .create(CreateNetworkTokenRequest.builder()
    .tokenIntentId("c06d0789-0a38-40be-b7cc-c28a718f76f1")
    .expirationMonth(10)
    .expirationYear(2025)
  .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("4000000000000002")
    .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="USA"
        )
    )
)

# Using an existing token ID with an expiration date override
await client.network_tokens.create(
    token_id="c06d0789-0a38-40be-b7cc-c28a718f76f1",
    expiration_month=10,
    expiration_year=2025
)

# 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="USA"
        )
    )
)

# Using an existing token intent ID with an expiration date override
await client.network_tokens.create(
    token_intent_id="c06d0789-0a38-40be-b7cc-c28a718f76f1",
    expiration_month=10,
    expiration_year=2025
)

# Using raw card data
await client.network_tokens.create(
    data=Card(
        number="4000000000000002",
        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="USA"
        )
    )
)

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
expiration_month	No	integer	The expiration date override month to use for provisioning when `token_id` or `token_intent_id` is used. Must be provided with `expiration_year`
expiration_year	No	integer	The expiration date override four-digit year to use for provisioning when `token_id` or `token_intent_id` is used. Must be provided with `expiration_month`
cardholder_info	No	object	The cardholder information
merchant_id	No	uuid	Deprecated: use `configuration_merchant_id` instead. Legacy alias kept for backward compatibility with lower precedence. Selects configuration only.
configuration_merchant_id	No	uuid	The tenant merchant whose Network Token configuration is used. Selects configuration only. Defaults to the `BT-MERCHANT-ID` header merchant, then the tenant-level configuration
owner_merchant_id	No	uuid	The tenant merchant to associate the Network Token with. Must match the `BT-MERCHANT-ID` header merchant when both are supplied, and the source token's merchant when the source token is merchant-owned. See Merchant Context

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 token_id or token_intent_id, the source token or token intent must contain card data with number. Expiration dates must be present on the source record or provided as top-level expiration_month and expiration_year overrides.

Card Data Object

Attribute	Required	Type	Description
number	Yes	string	The card number to tokenize
expiration_month	Yes	integer	The card's expiration month
expiration_year	Yes	integer	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",
        "product": {
            "code": "A"
        },
        "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
}

When expiration dates are overridden, card.expiration_month and card.expiration_year will contain the override values without updating the source token or token intent. Provider-issued data and network_token expiration dates may differ from those card values.

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",
        "product": {
            "code": "A"
        },
        "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"
}

Get a Network Token Account

Retrieves the card art associated with a Network Token: the issuer logo, the full card image, and the card's background color. Use this to render the underlying card visually when a customer selects a saved card at checkout.

Each card network exposes card art differently, and some require a separate lookup. This endpoint normalizes those differences into a single response, so you don't have to integrate with Visa, Mastercard, American Express, and Discover individually.

This is a separate call from provisioning, so requesting card art adds no latency to creating a Network Token. Call it only when you need to display card art, and cache the result on your side rather than fetching it on every checkout view.

GET

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

Permissions

network-token:read network-token:reveal

At least one of these permissions is required to access the card art.

Request

cURL
Node
C#
Java
Python

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

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

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

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

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

Request Parameters

Attribute	Required	Type	Description
id	Yes	string	The ID of the network token to retrieve card art for

Response

Returns a network token account object if successful. Returns an error if the network token does not exist or the card art failed to retrieve.

{
    "card_art": {
        "background_color": "#1A1F71",
        "logo": {
            "url": "https://card-art.example.com/visa/logo.png",
            "description": "Issuer logo",
            "height": 100,
            "width": 100
        },
        "card_image": {
            "url": "https://card-art.example.com/visa/card.png",
            "description": "Card art image",
            "height": 969,
            "width": 1536
        }
    }
}

The url values are issued by the card network and differ per card. In the sandbox, logo and card_image URLs are replaced with Basis Theory-hosted placeholder images. See Testing for details.

Card art availability varies by network. When a network does not return card art for a token, logo, card_image, background_color, or any of their fields may be null. Fall back to a brand logo when these values are absent.

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.basistheory.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 directly to the caller if successful. The cryptogram and ECI are temporary and not added to the Network Token. Returns an error if there were validation errors, or the cryptogram failed to create.

Both long and short cryptograms are available through 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

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",
        "product": {
            "code": "A"
        },
        "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",
        "product": {
            "code": "A"
        },
        "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	Expiration month of the provider-issued Network Token data
`data.expiration_year`	integer	Four-digit expiration year of the provider-issued Network Token data
`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 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
`modified_by`	uuid	ID of the entity that last modified the network token
`modified_at`	date	Timestamp of when the network token was last modified
`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	Nullable	Description
`bin`	string	No	Six to eight digit BIN of the network token
`last4`	string	No	Last four digits of the network token
`expiration_month`	number	No	The 2-digit expiration month of the network token
`expiration_year`	number	No	The 4-digit expiration year of the network token
`brand`	string	Yes	The primary card brand
`funding`	string	Yes	The primary funding type of the network token
`segment`	string	Yes	The segmentation of the network token (eg., Consumer, Commercial)
`product`	object	Yes	Describes the card product. See Product for details
`issuer`	object	Yes	Describes the country and issuing bank. See Issuer for details
`issuer_country`	object	Yes	Describes the issuing country. See Issuer Country for details
`authentication`	string	Yes	The authentication type required for this network token
`additional`	array	Yes	Other records found for the same BIN. Each entry has the same shape as the primary record. See Card Additional below for details.

Network token properties show the primary network token details for the BIN. When more than one record matches the BIN, the extra records land in additional[] — most often co-badged secondary networks (e.g., STAR, PULSE, NYCE) on a primary brand, but also alternate issuers or funding types when a BIN spans them. When the primary brand, funding, issuer, or authentication doesn't match the network token you're handling, check additional[] for a record that does. Entries are unordered; match by field values, not by index.

If a network token number does not correspond to any supported card brand or known BIN Details, then brand, funding, segment, product, issuer, 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

Issuer Country

Attribute	Type	Description
`alpha2`	string	Issuing country ISO3166 alpha country code
`numeric`	string	Issuing country ISO3166 numeric country code
`name`	string	Issuing country name

Product

The card product identifies the specific product within a brand and funding type — for example, distinguishing Visa Classic from Visa Signature or Visa Infinite. These values are derived from BIN Details enrichment, so they share its coverage and accuracy.

Attribute	Type	Description
`code`	string	The card product code assigned by the issuing network. See the Product Code Reference for the full list of Visa and Mastercard codes. `null` when the network does not provide one.

Card Details

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

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

Network Token Account Object

Attribute	Type	Description
`card_art`	object	The normalized card art for the network token. See Card Art Object.

Card Art Object

Attribute	Type	Description
`background_color`	string	The recommended background color for the card, as a hex color string. May be `null`.
`logo`	object	The issuer or brand logo. See Card Art Image Object. May be `null`.
`card_image`	object	The full card art image. See Card Art Image Object. May be `null`.

Card Art Image Object

Attribute	Type	Description
`url`	string	The URL of the image. May be `null`.
`description`	string	A description of the image. May be `null`.
`height`	integer	The height of the image, in pixels. May be `null`.
`width`	integer	The width of the image, in pixels. May be `null`.

Deduplication

_extras.deduplicated: true is returned when a provisioning request results in an existing Network Token being returned rather than a new one being created. When this happens, the new request's parameters are not applied, and the response reflects the existing token unchanged.

Deduplication is PAN-based: the same PAN within a tenant returns the existing Network Token. It keys on the PAN only, so provisioning the same PAN with a different expiration_month or expiration_year returns the existing token unchanged and the submitted expiration is not applied. The sandbox and production environments behave consistently, so you can validate idempotent provisioning before going live.

Scope: Deduplication is tenant-scoped. Two tenants provisioning the same PAN each receive their own Network Token.

Input sources: Deduplication applies regardless of whether the card is provided via data (raw card), token_id, or token_intent_id, as long as they resolve to the same underlying PAN.

A deduplicated response looks like:

{
    "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"
        }
    },
    "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",
    "_extras": {
        "deduplicated": true
    }
}

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​

Get a Network Token Account​

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​

Issuer Country​

Product​

Card Details​

Cryptogram Object​

Extras Object​

Network Token Account Object​

Card Art Object​

Card Art Image Object​

Deduplication​

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

Get a Network Token Account

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

Issuer Country

Product

Card Details

Cryptogram Object

Extras Object

Network Token Account Object

Card Art Object

Card Art Image Object

Deduplication