# Network tokens

Network tokens are unique digital identifiers used to provide symbolic placeholder data across the payment flow, instead of the primary account number (PAN). Using network tokens:

- Reduces declines due to expired or replaced cards because the card schemes automatically update the underlying card details
- Reduces customer friction because the underlying card details are updated by the card schemes without any action by the customer
- Provides an additional security layer and reduces the risk of fraud because sensitive card details are only ever exposed to the card scheme and issuer

Visa and Mastercard provision network tokens via the Visa Token Service (VTS) and Mastercard Digital Enablement Service (MDES), respectively.

> **Information**
>
> For more information, see the [network tokens](https://www.checkout.com/blog/network-tokens-explained) blog post.

---

## Network tokenization process

When you request network tokenization, the transaction goes through the following process:

1. Initialization – The customer enters their full card details during checkout on your website.
2. Provisioning request – You share the full card details with Checkout.com via the payment request. Checkout.com uses the card details to request a network token from the card scheme.
3. Network token processing – The card scheme automatically generates a network token and shares this with the issuer and Checkout.com.
4. Storage – Checkout.com stores the network token in your Vault for future use.

In future payment requests you can use the network token instead of the full card details. If you do so, the transaction goes through the following process:

1. Authorization – You request a payment using a card or payment instrument. If Checkout.com detects that a network token is available, we send this to the card network instead of the card details. The card network generates a cryptogram for the authorization which is unique to the combination of the network token, the merchant, and the specific transaction.
2. Decryption – The card scheme decrypts the network token to retrieve the card details. The details are shared with the issuer for verification.
3. Payment processing – The issuer verifies the card details. The transaction is processed and the payment is approved.

If the customer's card expires or is replaced, the card scheme automatically updates the network token's underlying card details.

---

## Asynchronous and synchronous provisioning

### Asynchronous provisioning

By default, network tokens are provisioned asynchronously.

The initial payment in which you request provisioning is processed with full PAN (FPAN), while the card details are tokenized in the background.

If provisioning is successful, you can use the network token in subsequent payment requests.

### Synchronous provisioning

The initial payment in which you request provisioning is not processed until a network token is available.

If provisioning is successful, you can use the network token to process the initial payment.

> **Information**
>
> To enable synchronous provisioning, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).

---

## Request network token provisioning during payment

By default, Checkout.com automatically:

- Requests network token provisioning on your behalf if you request a Visa or Mastercard payment with a new card
- Provides a network token if you request a payment with a card that was already provisioned

If you do not want to request network token provisioning, set the `processing.provision_network_token` field to `false` in your payment request.

> **Information**
>
> You can also request network token provisioning when you [Create an instrument](https://api-reference.checkout.com/tag/Instruments/#operation/createAnInstrument!path=1/type&t=request) by setting the `network_token.provision` field to `true`.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "source": {
    "type": "card",
    "number": "4242424242424242",
    "expiry_month": 12,
    "expiry_year": 2022
  },
  "amount": 6500,
  "currency": "USD",
  "processing": {
    "provision_network_token": true
  },
  "processing_channel_id": "processing_channel_id"
}
```

### Response example

```json
{
  "id": "pay_mbabizu24mvu3mela5njyhpit4",
  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
  "amount": 6540,
  "currency": "USD",
  "approved": true,
  "status": "Authorized",
  "auth_code": "770687",
  "response_code": "10000",
  "response_summary": "Approved",
  "processed_on": "2024-09-10T10:11:12Z",
  "processing": {
    "pan_type_processed": "fpan",
    "cko_network_token_available": true
  },
  "links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
    },
    "action": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
    }
  }
}
```

If provisioning is successful, Checkout.com automatically:

- Uses the network token in future [payment requests](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payments-api.md#Request_a_payment_with_a_network_token)
- Keeps the network tokens up to date by handling token lifecycle events from card schemes and issuers

---

## Request network token provisioning for your payment method

You can request Checkout.com to synchronously provision a network token for your payment method.

Call the [Provision a network token](https://api-reference.checkout.com/tag/Network-Tokens/#operation/provisionNetworkToken) endpoint, and provide the payment details you want to provision a token for:

- If you store your customer's card in Vault, provide a payment instrument.
- If you have your own card-on-file system, provide the full card details.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/network-tokens`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/network-tokens`

#### Request examples

**Payment instrument**

```json
{
  "source": {
    "type": "id",
    "id": "src_wmlfc3zyhqzehihu7giusaaawu"
  }
}
```

**Full card details**

```json
{
  "source": {
    "type": "card",
    "number": "4539467987109256",
    "expiry_month": "10",
    "expiry_year": "2027"
  }
}

```

#### Response example

```json
{
  "card": {
    "last4": 6378,
    "expiry_month": 5,
    "expiry_year": 2025
  },
  "network_token": {
    "id": "nt_xgu3isllqfyu7ktpk5z2yxbwna",
    "state": "active",
    "number": 5436424242424242,
    "expiry_month": 5,
    "expiry_year": 2025,
    "type": "vts",
    "payment_account_reference": "5001a9f027e5629d11e3949a0800a",
    "created_on": "2020-02-11T15:57:32.435+00:00",
    "modified_on": "2020-02-11T15:57:32.435+00:00"
  },
  "token_requestor_id": 1234567890,
  "_links": {
    "self": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna",
    "cryptogram": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna/cryptograms"
  }
}
```

- If you receive a `200 – Responding with existing network token` response, Checkout.com has already assigned a network token for this payment method.
- If you receive a `201 – Network token provisioned` response, Checkout.com successfully provisioned a network token for the payment method.

In both cases, the network token details are returned in the `network_token` object of the response.

---

## View network token provisioning results

You can monitor the results of your network token provisioning requests in the Dashboard.

1. Sign in to the [Dashboard](https://dashboard.checkout.com).
2. Go to _Vault_ > _Network tokens_.

From this page, you can view:

- The card scheme response to a provisioning request, via a [network token provisioning code](https://www.checkout.com/docs/developer-resources/codes/network-token-provisioning-codes.md)
- The percentage of successful and unsuccessful provisioning requests
- The total number of provisioning requests
- A breakdown of the success and failure rates for each card scheme
- A breakdown of the most common failure reasons for each card scheme

---

## Full PAN fallback

If a payment you requested using a network token is declined with any of the following [API response codes](https://www.checkout.com/docs/developer-resources/testing/codes/api-response-codes.md), Checkout.com automatically retries the payment using the full PAN (FPAN):

- `20003 - Invalid merchant or service provider`
- `20030 - Format error`
- `20068 - Response received too late / Timeout`
- `20091 - Issuer unavailable or switch is inoperative`
- `20096 - System malfunction`

> **Information**
>
> Using FPAN may incur a higher scheme fee in some regions. To opt out of full PAN fallback, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).

For providing full card details for a third-party network token, see [Request a payment with a fallback card](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payments-api.md#Request_a_payment_with_a_fallback_card)

---

## Use your network tokens in other platforms

You can request and extract your Checkout.com network tokens and cryptograms to use them with the acquirer and processor of your choice. You can also configure webhooks to receive token lifecycle updates to help you manage your network tokens correctly.

After [requesting network token provisioning](#Request_network_token_provisioning_for_your_payment_method), call the [Get network token](https://api-reference.checkout.com/tag/Network-Tokens/#operation/getNetworkToken) endpoint and provide the `network_token.id` value from the provisioning response as the `{id}` path parameter.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`GET` `https://{prefix}.api.checkout.com/network-tokens/{id}`

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/network-tokens/{id}`

#### Response example

```json
{
  "card": {
    "last4": 6378,
    "expiry_month": 5,
    "expiry_year": 2025
  },
  "network_token": {
    "id": "nt_xgu3isllqfyu7ktpk5z2yxbwna",
    "state": "active",
    "number": 5436424242424242,
    "expiry_month": 5,
    "expiry_year": 2025,
    "type": "vts",
    "payment_account_reference": "5001a9f027e5629d11e3949a0800a",
    "created_on": "2020-02-11T15:57:32.435+00:00",
    "modified_on": "2020-02-11T15:57:32.435+00:00"
  },
  "token_requestor_id": 1234567890,
  "_links": {
    "self": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna",
    "cryptogram": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna/cryptograms"
  }
}
```

Use the `network_token.number` to retrieve the network token value.

To use the network token with other platforms, you must also retrieve the cryptogram associated with the transaction.

### Retrieve a cryptogram

Alongside a network token, card schemes also generate a cryptogram for each authorization. This cryptogram is unique to the token, the merchant, and the transaction.

When the card scheme receives the network token, it decrypts the token and retrieves the original card details. The scheme then shares the card details with the issuer for verification.

To retrieve the cryptogram for a network token, call the [Request a cryptogram](https://api-reference.checkout.com/tag/Network-Tokens/#operation/provisionCryptogram) endpoint and provide the network token's `id` as the `{id}` path parameter.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/network-tokens/{id}/cryptograms`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/network-tokens/{id}/cryptograms`

#### Request example

```json
{
  "transaction_type": "recurring"
}
```

#### Response example

```json
{
  "cryptogram": "AhJ3hnYAoAbVz5zg1e17MAACAAA=",
  "eci": 7,
  "_links": {
    "self": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna/cryptograms",
    "network-token": "https://{prefix}.api.checkout.com/network-tokens/nt_xgu3isllqfyu7ktpk5z2yxbwna"
  }
}
```

## Remove a network token

To remove a network token, call the [Permanently delete a network token](https://api-reference.checkout.com/tag/Network-Tokens/#operation/deleteNetworkToken) endpoint, and provide the network token's `id` as the `{id}` path parameter.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`PATCH` `https://{prefix}.api.checkout.com/network-tokens/{id}/delete`

**Sandbox**

`PATCH` `https://{prefix}.api.checkout.com/network-tokens/{id}/delete`

#### Request example

```json
{
  "initiated_by": "token_requestor",
  "reason": "other"
}
```

## Get lifecycle notifications

When card schemes provision a network token, they also keep track of its lifecycle. If an update is required, the schemes contact us with the updated state of the token.

To receive these updates, subscribe to the [network token webhook](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Network_tokens).

See also [Configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md).

---

## Next steps

**[Network token provisioning codes](https://www.checkout.com/docs/developer-resources/codes/network-token-provisioning-codes.md)**

View Mastercard and Visa responses to network token provisioning requests.

**[Update stored credentials](https://www.checkout.com/docs/payments/store-and-manage-credentials/update-stored-credentials.md)**

Use the Real-Time Account Updater service alongside network tokens to automatically update stored payment credentials.