Skip to main content

Network Tokens Implementation

Enterprise-ready network token payments with reduced PCI scope and issuer trust.

Network tokenization replaces raw card numbers with issuer-managed tokens for secure reuse, enabling flexible, PSP-agnostic payment flows with full programmatic control over token lifecycle, authentication, and processor routing—without requiring every transaction to pass through the vault.

Network Tokens Implementation Diagram

This guide covers the payment lifecycle with Basis Theory Network Tokens, from provisioning and the first customer-initiated transaction (CIT) to subsequent merchant-initiated transactions (MITs), including processor integrations that keep sensitive card data out of your environment and aligned with issuer expectations.

If you are not yet collecting your customers' cards with Basis Theory, here are a few guides you can explore:

Getting Started​

To get started, you will need to create a Basis Theory Account and a TEST Tenant.

Be sure to use your work email (e.g., john.doe@yourcompany.com)
Ensure that you have completed the Network Tokens Setup guide. This step is only required once.

Private Application​

You will need a Private Application to allow your backend to call Basis Theory APIs. Click here to create one using the Basis Theory Customer Portal.

This will create an application with the following Access Controls:

  • Permissions: network-token:create, network-token:reveal, proxy:invoke
Save the key from the created Private Application as it will be used later in this guide.

Provision a Network Token​

After a card has been collected from the user, merchants can provision Network Tokens against the card networks by calling the Create a Network Token API while passing either the token_intent_id or the token_id. This step is performed only once per card.

curl 'https://api.basistheory.com/network-tokens' \
-X 'POST' \
-H 'BT-API-KEY: <PRIVATE_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
  "token_intent_id": "d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4",
  "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"
    }
  }
}'

If the card information is correct and the issuer supports it, a new Network Token will be generated:

Network Token Response
{
  "id": "1a97a7f6-5d7e-4a8e-ad08-c2472cfedf7f",
  "tenant_id": "4aee08b9-5557-474b-a120-252e01fc7b0f",
  "data": {
    "number": "4446878164352273",
    "expiration_month": 11,
    "expiration_year": 2030
  },
  "card": {
    "last4": "0002",
    "expiration_month": 10,
    "expiration_year": 2027
  },
  "network_token": {
    "bin": "444687",
    "last4": "2273",
    "expiration_month": 11,
    "expiration_year": 2030,
    "brand": "visa",
    "funding": "credit",
    "authentication": "sca_required",
    "issuer": {
      "country": "GB",
      "name": "3DS Test Cards (TEST)"
    },
    "issuer_country": {
      "alpha2": "GB",
      "name": "CENTRAL FEDERAL SAVINGS AND LOAN ASSOCIATION",
      "numeric": "826"
    },
    "segment": "Commercial"
  },
  "par": "V2831416512995186306443704057",
  "status": "active",
  "created_by": "0bc89db5-fadd-4d57-af93-10472e35ebd3",
  "created_at": "2025-03-10T14:23:56.5580574+00:00"
}
Including the card’s CVC can help reduce issuer risk scoring. We recommend attempting Network Token provisioning immediately after first collecting card information, or after re-collecting the CVC for previously saved cards.

What you should store in your database:

  1. [Required] The Network Token id, associating it with the rightful customer account.
  2. The Network Token data, enabling you to process payments without having to fetch it later.

Active Card Check​

Network Token provisioning can act as an early validation step during card onboarding, indicating that a card is real, recognized by the network, and eligible for tokenized transactions. Successful provisioning reflects issuer participation at tokenization time and may help reduce false-positive declines in later payments.

However, provisioning is not a payment verification mechanism and is subject to coverage limitations. A card may be valid and payment-ready yet still be ineligible for network tokenization due to issuer, network, region, or use-case constraints. Provisioning does NOT:

  • Authorize a transaction
  • Confirm funds availability
  • Validate CVC or expiry with transaction-level guarantees
  • Establish cardholder intent or provide liability shift
  • Does not replace a $0 or small-amount authorization where required

Test Cases and Error Handling​

Network Token provisioning can fail for issuer, network, or data-related reasons, and should be handled explicitly in your integration. We recommend implementing the scenarios outlined in our Network Token test cases and error handling documentation to ensure clear remediation paths, appropriate retries, and a smooth user experience.

First Charge​

Once a Network Token has been provisioned, merchants can process customer-initiated transactions (CITs) using the token in place of the card number, allowing issuers to apply dynamic authentication and token-specific controls during authorization.

Generating a Cryptogram​

A cryptogram is a transaction-specific, one-time security value generated by the issuer for a Network Token and is commonly required for customer-initiated transaction authorizations. It allows the issuer to verify that the transaction is fresh, bound to the specific request, and authorized in real time by the customer, providing stronger protection than static card data alone.

This is done by calling the Generate a Cryptogram API passing the Network Token id:

Generate a Cryptogram
curl 'https://api.basistheory.com/network-tokens/<NETWORK_TOKEN_ID>/cryptogram' \
-X 'POST' \
-H 'BT-API-KEY: <PRIVATE_API_KEY>' \
-H 'Content-Type: application/json'

Which returns a cryptogram and associated ECI:

Cryptogram Response
{
  "cryptogram": "5hgXjWJBDkiONPQ6EFxtgA==",
  "eci": "07"
}

Processing Payment​

Now that you have a Network Token and a cryptogram, both handled outside of PCI scope, you can route these credentials directly to your payment processor or acquirer API for authorization:

In Checkout.com, you can charge with a Network Token by calling the /payments API.

Request a Payment
curl 'https://api.sandbox.checkout.com/payments' \
-X 'POST' \
-H 'Authorization: Bearer <CHECKOUT_SECRET_KEY>' \
-H 'Content-Type: application/json' \
--data '{
  "source": {
    "type": "network_token",
    "token_type": "vts",
    "number": "4446878164352273",
    "expiry_month": "11",
    "expiry_year": "2030",
    "eci": "07",
    "cryptogram": "5hgXjWJBDkiONPQ6EFxtgA=="
  },
  "amount": 1000,
  "currency": "USD",
  "processing_channel_id": "pc_svyx12xvaaduraq3ckb2gwnvzq"
}'
Payment Response
{
  "id": "pay_myvj6zxrt45edgrswrliyxbtnq",
  "approved": true,
  "status": "Authorized",
  "amount": 1000,
  "currency": "USD",
  "source": {
    "type": "card",
    "id": "src_gguer4xlawke3ctljczft7573a",
    ...
  },
  "scheme_id": "647537243670773",
  ...
}

Save the Network Transaction identifier returned by the processor during the initial transaction. This allows you to seamlessly charge the card with new processors or acquirers in the future and achieve the best approval rates. Refer to your current processor’s documentation or support for guidance on accessing this value.

Subsequent Charges​

After the initial customer-initiated transaction, merchants can process merchant-initiated transactions (MITs) using the stored Network Token for follow-on charges such as subscriptions, renewals, or delayed captures. These transactions rely on stored-credential indicators and the original customer mandate, and typically do not require generating a new cryptogram (though some processors, such as Adyen, may still expect cryptogram fields in the request).

In Checkout.com, you can charge with a Network Token by calling the /payments API.

Pass the Network Transaction identifier of the first charge into the previous_payment_id field.

Request a Payment
curl 'https://api.sandbox.checkout.com/payments' \
-X 'POST' \
-H 'Authorization: Bearer <CHECKOUT_SECRET_KEY>' \
-H 'Content-Type: application/json' \
--data '{
  "source": {
    "type": "network_token",
    "token_type": "vts",
    "number": "4446878164352273",
    "expiry_month": "11",
    "expiry_year": "2030",
    "stored": true
  },
  "amount": 1000,
  "currency": "USD",
  "payment_type": "Recurring",
  "merchant_initiated": true,
  "processing_channel_id": "pc_svyx12xvaaduraq3ckb2gwnvzq",
  "previous_payment_id": "<first_network_transaction_identifier>"
}'
Payment Response
{
  "id": "pay_myvj6zxrt45edgrswrliyxbtnq",
  "approved": true,
  "status": "Authorized",
  "amount": 1000,
  "currency": "USD",
  "source": {
    "type": "card",
    "id": "src_gguer4xlawke3ctljczft7573a",
    ...
  },
  "scheme_id": "647537243670773",
  ...
}
Ensure to properly flag the MIT type (for example, Recurring, Unscheduled Credential-on-File, Installment, Delayed Charge, Incremental, or MOTO) so issuers can correctly interpret the mandate and apply appropriate authorization rules.

FAQ​

How broad is Network Token coverage?​

Network Token coverage varies by issuer, region, and use case, but is already strong in mature markets. In the United States and Europe, an estimated 80–90% of card volume is eligible for network tokenization, driven by widespread Tier-1 issuer adoption.

Networks are making tokenization a strategic priority: Visa positions network tokens as the preferred credential for digital commerce, highlighting improved authorization rates and reduced fraud (Visa Tokenization Overview), while Mastercard has publicly committed to making tokenized credentials the default for e-commerce and reaching 100% e-commerce tokenization in Europe by 2030 (Mastercard 2030 vision).

Coverage is not yet universal: some issuers, card programs, regions, or flows may still be ineligible. Integrations should always detect token availability and support fallbacks (such as PAN or gateway tokens) to ensure consistent payment acceptance.

How can I manage the lifecycle of a Network Token?​

Network Tokens support standard lifecycle actions that let you control how and when a token can be used. You can temporarily suspend a token to prevent transactions without losing the ability to restore it later, reactivate a suspended token to resume payments, or permanently delete a token when it is no longer needed. These actions allow you to respond to events like account changes, suspected fraud, or customer requests while maintaining control over token usage.

Does Network Token provisioning add latency to my checkout flow?​

Network Token provisioning depends on card network and issuer response times, not the merchant integration itself. Provisioning typically completes in 300–1000 ms and is a one-time operation per card, making it best suited for card onboarding rather than checkout.

What is the latency impact of generating a cryptogram?​

Cryptogram generation is a lightweight, real-time operation backed by the networks and issuers. Typical response times are 100–500 ms, making it suitable for synchronous customer-initiated checkout flows.

What are common ways to provision a Network Token during “add card” in checkout?​

A common synchronous approach is a two-step flow that keeps checkout straightforward while still maximizing token coverage:

  1. Add card (setup step): Collect the card and attempt Network Token provisioning immediately. If provisioning succeeds, store the Network Token id (and optionally token data) for reuse. If it fails due to coverage or issuer rules, fall back to storing the underlying card token and proceed.
  2. Place order (payment step): When the customer confirms checkout, generate a cryptogram for the Network Token (CIT) and submit the authorization to your processor using the Network Token + cryptogram/ECI.

This works well when you want tokenization to be “ready” by the time the user clicks Pay, and it keeps failures contained to the “add card” moment.

Can we accept the order first and process payment asynchronously (Amazon-style)?​

Yes. An async approach prioritizes checkout conversion by decoupling order placement from network and issuer-dependent token operations:

  1. Place order first: Create the order and confirm inventory/shipping, then queue payment processing in the background.
  2. Provision and charge asynchronously: Attempt Network Token provisioning (if not already done), generate a cryptogram if it’s a CIT-equivalent flow, and submit the authorization. If tokenization isn’t available, fall back to PAN-token-based processing.
  3. Handle outcomes: If the charge succeeds, finalize the order. If it fails, notify the customer to update their payment method or retry with a different card.

This pattern reduces user-visible latency and makes network/issuer variability less likely to interrupt checkout, at the cost of additional operational complexity (payment state machine, notifications, retries, and reconciliation).

How long is a cryptogram valid?​

Cryptograms are short-lived, single-use values generated for a specific transaction context. While exact validity windows are defined by the card networks and issuers, cryptograms are generally expected to be used immediately after generation. If a transaction is delayed, abandoned, or materially changed, a new cryptogram should be generated before retrying the authorization.

Can the same cryptogram be reused when retrying with a different processor?​

In some cases, yes, but only within a narrow window and when the transaction has not been authorized, the decline reason allows retry, and the transaction context remains unchanged. Cryptogram reuse behavior is ultimately governed by the networks and issuers, and support may vary by issuer and processor. When in doubt, generating a new cryptogram is the safest approach, especially if retrying after a delay or modifying any transaction details.

Do I need Account Updater if I have Network Tokens?​

Network Tokens provide built-in lifecycle management, automatically handling events like reissues and expiration updates for supported cards. However, coverage is not universal, so you may still want to use Account Updater as a fallback for cards or regions that do not support network tokenization, ensuring continuity across your entire card portfolio.

Can I backfill Network Tokens for cards I already have on file?​

Yes. Existing cards stored in the vault can be retroactively network-tokenized through a backfill process. Because CVC/CVV is typically not available for stored cards, backfilled provisioning depends on issuer and network eligibility and may result in lower coverage compared to tokens provisioned at initial card collection. This process is coordinated with Basis Theory Support and allows merchants to extend the benefits of network tokenization to previously stored credentials without requiring customers to re-enter their card details.

Last updated on