Skip to main content

Network Tokens


Unlike standard tokens that are converted back to the PAN during authorization, network tokens remove the PAN from the payment flow. Each network token is provisioned with its own expiration date and is paired with a dynamic cryptogram. Tokens can be restricted to a specific merchant, device, or transaction context.

Initially introduced for digital wallets, network tokens now support card-on-file (COF) use cases such as subscriptions, recurring payments, and one-click checkout, enabling secure storage and reuse of payment credentials.

tokens can be linked to network tokens:

  • Instrument identifier tokens represent the underlying account
  • Payment instrument tokens represent a stored payment method
  • Customer tokens represent a stored customer profile

Network Tokens vs. Instrument Identifier Tokens

The network scheme generates network tokens, which pass through an acquirer and are detokenized by the payment network or the issuer. This removes the PAN from transaction processing. Network tokens can be mapped to instrument identifier tokens, and the minimum card data required to request one is the PAN and the expiration date.

Network tokens improve authorization rates for credentials-on-file and recurring payments, and they support customer tracking through the payment account reference (PAR), a consumer identifier that is less sensitive than the PAN.

The instrument identifier token is the TMS token a network token maps to, because it is the token that holds the tokenized account number. This table compares the two:

FeatureInstrument identifier tokenNetwork token
Generated byThe TMS token vaultThe card network scheme
ContainsThe tokenized PAN for card payments, or a US or Canadian bank account and routing numberA network-generated value that replaces the PAN during transaction processing
Detokenized byTMS, which sends the PAN to the issuer for authorizationThe payment network or the issuer
MappingHolds the associated network tokenMapped to an instrument identifier token
Minimum data to createThe account number being tokenizedThe PAN and the expiration date
Customer-initiated transactionsThe token in the requestThe token and a cryptogram
Authorization ratesStandardImproved for credentials-on-file and recurring payments

Key Benefits and Features

Network tokenization helps improve payment security, performance, and customer experience:

  • Enhanced security: Tokens are domain-restricted and tied to your Token Requestor ID (TRID), so they can only be used in your environment. Tokens cannot be reused outside that domain and can be deactivated without reissuing cards.
  • Higher authorization rates: Each transaction includes a dynamic cryptogram. This provides additional assurance to issuers and helps improve authorization performance.
  • Automatic updates: Card life-cycle changes, such as reissues or expirations, are updated automatically. You receive updates without handling new card numbers, reducing payment disruptions.
  • Reduced PCI scope: By storing tokens instead of raw card data, you can lower PCI compliance requirements and the associated costs.
  • Simplified checkout: Cardholders can complete transactions without re-entering CVV, reducing friction and improving conversion.
  • Enhanced checkout experiences: Support for card art and push provisioning enables seamless onboarding and enhanced checkout or wallet interactions.

This section contains information about how to manage network tokens using .

You can manage network tokens using the Tokenized Cards, Payment Credentials, and Instrument Identifier APIs.

Tokenized Cards API

The Tokenized Cards API enables you to create, retrieve, and manage network tokens:

  • Provision a Network Token for a Card Number
  • Retrieve a Network Token
  • Delete a Network Token

The Tokenized Cards API also supports these value-added capabilities for network tokenization:

  • Provision a Network Token for a Consumer
  • Provision a Network Token for a Device Token
  • Provision a Network Token with Push Provisioning

For information about enabling network tokenization and setting up your token requestor ID, see Network Token Enablement.

To retrieve payment credentials, including a cryptogram for a network token, see the Payment Credentials section.

Use this endpoint to access the Tokenized Cards API:

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

Payment Credentials API

The Payment Credentials API enables you to generate and retrieve network token payment credentials such as:

  • Network token value
  • Cryptogram (Visa and Mastercard only)
  • Dynamic card verification value (CVV) (American Express only)

Use this endpoint to access the Payment Credentials API:

POST /tms/v2/tokens/{tokenId}/payment-credentials

POST /tms/v2/tokens/{tokenId}/payment-credentials

Additional Provisioning Options

You can also provision a network token while creating an instrument identifier token or when you process a payment:

POST /tms/v1/instrumentidentifiers

POST /tms/v1/instrumentidentifiers

POST /pts/v2/payments

POST /pts/v2/payments

Digital Commerce Authentication Program

The Digital Commerce Authentication Program (DCAP) provides you with a way to enhance the security and reliability of card-not-present transactions by providing enhanced data without adding complexity in checkout. DCAP helps the clients that use network tokenization to provide more information to issuers when purchases are made using network tokens.

DCAP does not require the token to be an authenticated payment credential. Instead, you can include additional fields in the transaction request that are sent to the issuer and are used in risk scoring. This enables issuers to make a more informed authorization decision.

Network Token Provisioning Workflows

These workflows show how merchants and partners provision network tokens.

Merchant Model: Network Token Provisioning

This workflow shows the process of network token provisioning for merchants.

Tokenizing PAN

  1. The customer enters their card data and sends the PAN to the merchant.
  2. The merchant sends the PAN to Token Management Service.
  3. Token Management Service generates a TMS token and synchronously provisions a network token from the card brand.
  4. Token Management Service sends the merchant the TMS token, expiration date, suffix, and payment account reference (PAR).
  5. The merchant stores the TMS token ID and network token flag and sends the customer the masked card number.

Cryptogram Retrieval

  1. The merchant requests the cryptogram using a TMS token from Token Management Service.
  2. Token Management Service looks up the network token and sends the token metadata to the card brand.
  3. The card brand generates the cryptogram and sends it to Token Management Service.
  4. Token Management Service sends the network token and cryptogram to the merchant.
  5. The merchant uses the network token along with the cryptogram to start the authorization.

PAR Retrieval

  1. The merchant retrieves the TMS token and sends to Token Management Service.
  2. Token Management Service looks up the token and retrieves the PAR.
  3. Token Management Service sends the PAR to the merchant.
  4. The merchant stores the PAR.

Partner Model: Network Token Provisioning

This workflow shows the process of network token provisioning for partners.

Tokenizing PAN

  1. The customer enters their card data and sends the PAN to the merchant.
  2. The merchant sends the PAN to Token Management Service.
  3. Token Management Service generates a TMS token and synchronously provisions a network token from the card brand.
  4. Token Management Service sends the merchant the TMS token, expiration date, suffix, and payment account reference (PAR).
  5. The merchant stores the TMS token ID and network token flag and sends the customer the masked card number.

Cryptogram Retrieval

  1. The merchant requests the payment credentials using a TMS token from Token Management Service.
  2. Token Management Service looks up the network token and sends the token metadata to the card brand.
  3. The card brand generates the cryptogram and sends it to Token Management Service.
  4. Token Management Service sends the network token and cryptogram to the merchant.
  5. The merchant uses the network token along with the cryptogram to start the authorization.

PAR Retrieval

  1. The merchant retrieves TMS token and sends it to Token Management Service.
  2. Token Management Service looks up the token and retrieves the PAR.
  3. Token Management Service sends the PAR to the merchant.
  4. The merchant stores the PAR.

Endpoints

Tokenized Cards

MethodPathDescription
POST/tms/v2/tokenized-cardsProvision a network token for a card number
GET/tms/v2/tokenized-cards/{tokenizedCardId}Retrieve a network token
DELETE/tms/v2/tokenized-cards/{tokenizedCardId}Delete a network token

Payment Credentials

MethodPathDescription
POST/tms/v2/tokens/{tokenId}/payment-credentialsGenerate standard payment credentials
POST/tms/v2/tokens/{tokenId}/payment-credentials-dcapGenerate DCAP payment credentials
POST/tms/v2/tokens/{tokenId}/payment-credentials-vppGenerate payment passkey credentials

Payments and Transactions

MethodPathDescription
POST/pts/v2/paymentsAuthorize a payment (with or without network token)
PATCH/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}Update merchant-initiated transaction (MIT) authorization options

Card Art

MethodPathDescription
GET/tms/v2/tokens/{tokenId}/vts/assets/card-art-combinedRetrieve card art

Lifecycle Management

MethodPathDescription
POST/tms/v2/tokens/{tokenId}/lcm-events/simulateSimulate LCM (Lifecycle Management) events

Provision a Network Token for a Card Number

This section describes how to provision a network token for a card number.

Network tokens that are provisioned by are card-on-file (COF) tokens.

Endpoint

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

Example

{  "source": "ONFILE",  "card": {    "number": "X622943123116478",    "expirationMonth": "12",    "expirationYear": "2026"  }}
{  "_links": {    "self": {      "href": "/tms/v2/tokenized-cards/518CA1611EF98697E063AF598E0ADFB9"    },    "instrumentIdentifier": {      "href": "/tms/v1/instrumentidentifiers/7031530000033441624"    }  },  "id": "518CA1611EF98697E063AF598E0ADFB9",  "object": "tokenizedCard",  "state": "ACTIVE",  "enrollmentId": "15372f0f2bdf79725a1516de0288de01",  "tokenReferenceId": "8d40eed53be76d63c665111dc1d46e01",  "paymentAccountReference": "V0010013025104530884197510742",  "number": "489537XXXXXX1624",  "expirationMonth": "12",  "expirationYear": "2034",  "type": "visa",  "card": {    "suffix": "6478",    "expirationMonth": "12",    "expirationYear": "2026"  },  "source": "ONFILE"}
FieldTypeDescription
card.numberstringThe card number.
card.expirationMonthstringThe expiration month of the card in two-digit format (MM). For example, 12.
card.expirationYearstringThe expiration year of the card in four-digit format (YYYY). For example, 2026.
sourcestringSet to ONFILE.

Retrieve a Network Token

This section contains the required information for partners, merchants, and acquirers to retrieve a network token.

Endpoint

GET /tms/v2/tokenized-cards/{tokenizedCardId}

GET /tms/v2/tokenized-cards/{tokenizedCardId}

GET /tms/v2/tokenized-cards/{tokenizedCardId}

GET /tms/v2/tokenized-cards/{tokenizedCardId}

GET /tms/v2/tokenized-cards/{tokenizedCardId}

The {tokenizedCardId} is the tokenized card ID returned in the id field when you provisioned the network token.

Example

GET /tms/v2/tokenized-cards/223ACDECF1681954E063A2598D0A786D
{  "_links": {    "self": {      "href": "/tms/v2/tokenized-cards/223ACDECF1681954E063A2598D0A786D"    },    "instrumentIdentifier": {      "href": "/tms/v1/instrumentidentifiers/7040890000006625091"    }  },  "id": "223ACDECF1681954E063A2598D0A786D",  "object": "tokenizedCard",  "state": "ACTIVE",  "enrollmentId": "FM4MMC00001441368fa429c85a5d4df5ad1875bfd2faa5eb",  "tokenReferenceId": "DM4MMC1US0000000a7fab5f3a27e49daaf1984f7b49ab2f6",  "number": "521415XXXXXX5091",  "expirationMonth": "10",  "expirationYear": "2027",  "type": "mastercard",  "card": {    "suffix": "0747",    "expirationMonth": "12",    "expirationYear": "2031"  },  "source": "ONFILE"}

Delete a Network Token

This section contains the required information for partners, merchants, and acquirers to delete a network token.

A successful delete response returns an empty HTTP 204 No Content status.

Endpoint

DELETE /tms/v2/tokenized-cards/{tokenizedCardId}

DELETE /tms/v2/tokenized-cards/{tokenizedCardId}

DELETE /tms/v2/tokenized-cards/{tokenizedCardId}

DELETE /tms/v2/tokenized-cards/{tokenizedCardId}

DELETE /tms/v2/tokenized-cards/{tokenizedCardId}

The {tokenizedCardId} is the tokenized card ID returned in the id field when you provisioned the network token.

Example

Request:

DELETE /tms/v2/tokenized-cards/223ACDECF1681954E063A2598D0A786D

Payment Credentials

This section describes how to generate and retrieve network token payment credentials such as network token value, cryptogram (Visa and Mastercard only), and dynamic card verification value (CVV, American Express only).

Network token payment credentials are returned as a JSON Web Encryption (JWE) response.

You can use the Payment Credentials API to retrieve the payment credentials for an existing customer, payment instrument, instrument identifier, or tokenized card.

Prerequisites

You must have the payment credentials service enabled for the vault from which the network token is retrieved. For information on how to enable the payment credentials service, see your vault hierarchy documentation.

You must have a message-level encryption (MLE) key from the to retrieve network token data. For information on how to create an MLE key, see your MLE setup documentation.

Standard Payment Credentials

Generate standard payment credentials including network token value and cryptogram (Visa and Mastercard only).

Endpoint

POST /tms/v2/tokens/{tokenId}/payment-credentials

POST /tms/v2/tokens/{tokenId}/payment-credentials

DCAP Payment Credentials

Generate DCAP (Dynamic Card Art Personalization) payment credentials.

Endpoint

POST /tms/v2/tokens/{tokenId}/payment-credentials-dcap

POST /tms/v2/tokens/{tokenId}/payment-credentials-dcap

Payment Passkey Credentials

Generate Payment Passkey credentials using the Payment Passkey service.

Endpoint

POST /tms/v2/tokens/{tokenId}/payment-credentials-vpp

POST /tms/v2/tokens/{tokenId}/payment-credentials-vpp

Encryption and Decryption

To retrieve and use encrypted payment credentials, you must retrieve the encrypted credential and decrypt the payload.

Step 1: Request the encrypted payment credentials

Send a POST request to the token cryptogram resource at /tms/v2/tokens/{instrumentIdentifierTokenId}/payment-credentials. The response is BASE 64 encoded text. For example:

JraWQiOiI5OWY5YmVjOTlmMzQ1MDJmMDE2NWIyYmJhYWYyODAxNDNhOTI0OWNjIiwiY3R5IjoianNvbiIsInR5cCI6IkpXVCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.uYCE2zysWJB8E562FGJl4YyotZEHw4Az-2fvhjaUWubuAZ2tmZm44oKUdsfsBLYWInxpMDUsiENTTHG_UJJ25Snhcft6eZGj79gW_S55ZAGAi1eYIJA08gr01U7P-1QIzQ5t6dlkTRZElYDiNjypSaVfQPQPODaGNfB04Li7Pt88i-PIspGafq9P7TgacPyKoIkvM5CwLWbwSZYN_jdFq8hEu4Dy7gqDpf0z-rCdtWggWpFbGwdurDrKCbLBoQ4dY7OckJoe2OOWH-O1h_7uZymDDUjnqWFRcHgjxY7bmWJz94i_r4QUaoTQiaaqgyP6A2H3Gmt6Dy4VpIzO2XgLQA._cLex9BPstYqqnfe.RMbdjAqWR6HaVZ7USbp6j-KWPC1jGc3Wzk4M_CwJ58X2NNZ5ekUpAvU28_MbqQ2W6MLhJ7ulgfU5mk9_Y5nvAW6Yh68Ctye2yOhgu_V_33aLmz3iZP5AEGi7HeJVng0hy4EaQHNb92XYXUV1mvFHJokA4cRaj3eKwh6v-1lRhB4uIgXU62ZanVGGu5c7UkVkf6JiigZarGJiY2DKCRjYnbQYkj4JNFY94JlS50wTnGrk3MiAJN9DYIU-6US98zWGJ8VhBwhMuXk1juqVBfifjJMFa_-vnJjGpq1ri2buZ7hMJG-x0PIYoHUGSFeqNrcLUjJxI0o8lnXfhj7DtfYvNc0e4g5U39xtk-T2TDnQfdekRVxgdxcVR4mZdEqUHBxYUWTSW4AbgV-fjuCGDCkUoPIgkZ95y4RJhSPZzjZHdulf2Fk3L7e-nto2PB25zUTt_aXeNBSH8zjmaI2ve6D3VN0ScduRMl_9PXv1876opHEGqgkKLSTXcTUasXKlzMEiUzLl3p5pN30KnVbryAzuU3hhmIMyyPpEQkp9h3WlD4sc5oH1E8YtihLlSTtTUNwX5dJuR6iVwpKqFxECqYPtDWlzXQDTedFqdTA4isE3MCs.th9qWPzsevuDYp--06oPOw

Step 2: Decode the BASE 64 encoded response

Decode the BASE 64 encoded response. The response is a decoded JWE response with an encrypted payload. For example:

{  "kid": "99f9bec99f34502f0165b2bbaaf280143a9249",  "cty": "json",  "typ": "JWT",  "enc": "A256GCM",  "alg": "RSA-OAEP-256"}<Encrypted payload>

Step 3: Decrypt the JWE encrypted payload

Decrypt the JWE encrypted payload. The response is the decrypted payload. For example:

{  "_links": {    "self": {      "href": "/tms/v2/tokens/A560EECDED74936DE0533F36CF0ACEBC/payment-credentials"    }  },  "tokenizedCard": {    "state": "ACTIVE",    "number": "4X24XX7118382281",    "expirationMonth": "11",    "expirationYear": "2031",    "type": "visa",    "cryptogram": "AF1ajnoLKKj8AAKhssPUGgADFA==",    "requestorId": "ABCD",    "card": {      "suffix": "2382",      "expirationMonth": "12",      "expirationYear": "2031"    },    "metadata": {      "cardArt": {        "combinedAsset": {          "id": "84cfb836af434859be62c766bdc9e510",          "_links": {            "self": {              "href": "/tms/v2/tokens/7030080000051311515/vts/assets/card-art-combined"            }          }        }      },      "issuer": {        "name": "issuing bank name",        "shortDescription": "The Bank Card",        "longDescription": "The Bank Card Platinum Rewards",        "country": "Country of issuing Bank",        "accountPrefix": "BIN",        "email": "[email protected]",        "phoneNumber": "1112223333",        "url": "http://www.example.com"      }    }  },  "card": {    "number": "402400XXXXXX2382"  },  "issuer": {    "paymentAccountReference": "V0000000000005109162731718000"  }}

Authorize a Payment Using a Network Token

This section describes how to authorize a payment using a network token instead of a raw card number.

Endpoint

POST /pts/v2/payments

POST /pts/v2/payments

POST /pts/v2/payments

POST /pts/v2/payments

POST /pts/v2/payments

Set these fields in the paymentInformation.tokenizedCard object to authorize a payment with a network token:

FieldTypeDescription
paymentInformation.tokenizedCard.numberstringThe network token value that you received from the token service provider.
paymentInformation.tokenizedCard.expirationMonthstringThe token expiration month that you received from the token service provider.
paymentInformation.tokenizedCard.expirationYearstringThe token expiration year that you received from the token service provider.
paymentInformation.tokenizedCard.cryptogramstringThe cryptogram that you retrieved for the network token.

For the full list of required and optional fields, supported processors, and a request and response example, see Authorizations with Payment Network Tokens.

Merchant Model: Network Token Authorizations (CIT)

This workflow shows a credentials-on-file (COF) authorization using a network token for a customer-initiated transaction (CIT):

  1. The customer makes a purchase and selects COF.
  2. The merchant submits an authorization to the payment processor using a TMS token.
  3. The payment processor uses the TMS token to look up the network token.
  4. The payment processor requests the cryptogram generated by the card brand.
  5. The payment processor sends the network token, cryptogram, and 3-D Secure data to the acquirer in the authorization request.
  6. The acquirer processes the authorization and sends the authorization result to the payment processor.
  7. The payment processor sends the authorization result to the merchant.
  8. The merchant updates the order and advises the customer on how to proceed depending on the authorization result.

Merchant Model: Network Token Authorizations (MIT)

This workflow shows a credentials-on-file (COF) authorization using a network token for a merchant-initiated transaction (MIT).

  1. The merchant sends the TMS token to the payment processor.
  2. The payment processor looks up the network token associated with the TMS token.
  3. The payment processor sends the network token and MIT COF data to the acquirer in the authorization request.
  4. The acquirer processes the authorization and sends the authorization result to the payment processor.
  5. The payment processor sends the authorization result to the merchant.
  6. The merchant updates the system to reflect the status of the transaction.
  7. The customer provides goods/service.

Partner Model: Network Token Authorizations (CIT)

This workflow shows a credentials-on-file (COF) authorization using a network token for a customer-initiated transaction (CIT).

The workflow begins when the customer makes a purchase from the merchant and selects a COF during payment.

  1. The customer makes a purchase and selects COF.
  2. The merchant requests the payment credentials and sends the TMS token to the payment processor.
  3. The payment processor uses the TMS token to look up the network token.
  4. The payment processor requests the cryptogram generated by the card brand.
  5. The payment processor sends the network token and cryptogram to the merchant.
  6. The merchant uses the network token along with the cryptogram to start the authorization.
  7. The merchant sends the network token, cryptogram, and 3-D Secure data to the acquirer in the authorization request.
  8. The acquirer processes the authorization and sends the authorization result to the merchant.
  9. The merchant sends the customer the authorization result from the acquirer.

Partner Model: Network Token Authorizations (MIT)

This workflow shows a credentials-on-file (COF) authorization using a network token for a merchant-initiated transaction (MIT).

  1. The merchant requests the payment credentials and sends the TMS token to the payment processor.
  2. The payment processor uses the TMS token to look up the network token.
  3. The payment processor sends the network token and cryptogram to the merchant.
  4. The merchant uses the network token along with the cryptogram to start the authorization.
  5. The merchant sends the network token and MIT COF data to the acquirer in the authorization request.
  6. The acquirer processes the authorization and sends the authorization result to the merchant.
  7. The merchant sends the customer the authorization result from the acquirer.

Authorize a Payment While Ignoring Network Token

This section describes how to authorize a payment ignoring a network token.

Endpoint

POST /pts/v2/payments

POST /pts/v2/payments

POST /pts/v2/payments

POST /pts/v2/payments

POST /pts/v2/payments

Example

{  "clientReferenceInformation": {    "code": "RTS-Auth"  },  "paymentInformation": {    "card": {      "expirationYear": "2031",      "expirationMonth": "12",      "type": "001"    },    "instrumentIdentifier": {      "id": "7010000000016241111"    }  },  "orderInformation": {    "amountDetails": {      "currency": "USD",      "totalAmount": "1.00"    }  },  "processingInformation": {    "capture": "false",    "commerceIndicator": "internet"  },  "tokenInformation": {    "networkTokenOption": "ignore"  }}
{  "_links": {    "authReversal": {      "method": "POST",      "href": "/pts/v2/payments/6769913443166412604951/reversals"    },    "self": {      "method": "GET",      "href": "/pts/v2/payments/6769913443166412604951"    },    "capture": {      "method": "POST",      "href": "/pts/v2/payments/6769913443166412604951/captures"    }  },  "clientReferenceInformation": {    "code": "RTS-Auth"  },  "id": "6769913443166412604951",  "orderInformation": {    "amountDetails": {      "authorizedAmount": "1.00",      "currency": "USD"    }  },  "paymentAccountInformation": {    "card": {      "type": "001"    }  },  "paymentInformation": {    "tokenizedCard": {      "type": "001"    },    "instrumentIdentifier": {      "id": "7030000000014911515",      "state": "ACTIVE"    },    "shippingAddress": {      "id": "F537CE8DBA2F032CE053AF598E0A64F2"    },    "paymentInstrument": {      "id": "F537E3D12322416EE053AF598E0AD771"    },    "card": {      "type": "001"    },    "customer": {      "id": "F537CE8DBA2C032CE053AF598E0A64F2"    }  },  "pointOfSaleInformation": {    "terminalId": "111111"  },  "processorInformation": {    "paymentAccountReferenceNumber": "V0010013019326121174070050420",    "approvalCode": "888888",    "networkTransactionId": "123456789619999",    "transactionId": "123456789619999",    "responseCode": "100",    "avs": {      "code": "X",      "codeRaw": "I1"    }  },  "reconciliationId": "744295942E2LY3F8",  "status": "AUTHORIZED",  "submitTimeUtc": "2023-02-21T14:55:44Z"}
FieldTypeDescription
clientReferenceInformation.code
paymentInformation.customer.id
paymentInformation.paymentInformation.id
paymentInformation.shippingAddress.id
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
processingInformation.capture
processingInformation.commerceIndicator
tokenInformation.networkTokenOptionSet the value to ignore.

Update Merchant-Initiated Transaction Authorization Options

This section describes how to update merchant-initiated transaction (MIT) authorization options.

Endpoint

PATCH /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

PATCH /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

PATCH /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

PATCH /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

PATCH /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

The {instrumentIdentifierTokenId} is the instrument identifier token ID returned in the id field when you created the instrument identifier token.

Provision a Network Token for a Consumer

When you provision a network token for an individual consumer in a wallet, you can manage the network token and payment credentials separately for that consumer. Provisioning network tokens for a consumer is supported for American Express, Mastercard, and Visa. This section describes how to provision a network token for a card number and a consumer ID.

Network tokens that are provisioned by are card-on-file (COF) tokens.

Endpoint

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

Example

{  "createInstrumentIdentifier": true,  "source": "ONFILE",  "consumerId": "123456",  "card": {    "number": "X895379980000580",    "expirationMonth": "12",    "expirationYear": "2023",    "securityCode": "123"  }}
{  "_links": {    "self": {      "href": "/tms/v2/tokenized-cards/7030000000014911515"    },    "instrumentidentifier": {      "href": "/tms/v1/instrument-identifier/7030000000042974378"    }  },  "id": "7030000000014911515",  "object": "tokenizedCard",  "state": "ACTIVE",  "source": "ONFILE",  "enrollmentId": "96eb80a56b76ae1d486e14f40b3d7a01",  "tokenReferenceId": "059ae2f74835647400c219884b7bc601",  "paymentAccountReference": "V0010013022298169667504231315",  "number": "489537XXXXXX9215",  "expirationMonth": "10",  "expirationYear": "2031",  "type": "001",  "card": {    "suffix": "0580",    "expirationMonth": "12",    "expirationYear": "2023"  },  "metadata": {    "cardArt": {      "combinedAsset": {        "id": "d3225702-354a-4f17-8c40-1727de7ffa57",        "_links": {          "self": {            "href": "/tms/v2/tokens/7030000000042974378/mdes/assets/card-art-combined"          }        }      }    },    "issuer": {      "name": "METROBANK CARD CORPORATION (A FINANCE COMPANY)",      "shortDescription": "METROBANK CARD CORPORATION"    },    "creator": "testrest"  }}
FieldTypeDescription
card.number
card.expirationMonth
card.expirationYear
createInstrumentIdentifierSet to true.
sourceSet to ONFILE.
consumerIdWhen this field is not included, a network token is provisioned only for the PAN in the request.
Optional Fields
FieldTypeDescription
card.securityCode

Provision a Network Token for a Device Token

This section describes how to create a network token for a given device token. You can also use this feature to provision a network token for a token provided by another token service provider.

A device token represents a payment credential that has been provisioned to a digital wallet or device. You can provision a network token for an existing device token.

Network tokens that are provisioned by are card-on-file (COF) tokens.

Endpoint

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

Example

{  "createInstrumentIdentifier": true,  "source": "TOKEN",  "card": {    "number": "X621943123037127",    "expirationMonth": "12",    "expirationYear": "2025",    "securityCode": "123"  }}
{  "_links": {    "self": {      "href": "/tms/v2/tokenized-cards/7030000000014911515"    },    "instrumentidentifier": {      "href": "/tms/v1/instrument-identifier/7030000000042974378"    }  },  "id": "7030000000014911515",  "object": "tokenizedCard",  "state": "ACTIVE",  "source": "TOKEN",  "enrollmentId": "96eb80a56b76ae1d486e14f40b3d7a01",  "tokenReferenceId": "059ae2f74835647400c219884b7bc601",  "paymentAccountReference": "V0010013022298169667504231315",  "number": "489537XXXXXX9215",  "expirationMonth": "10",  "expirationYear": "2031",  "type": "001",  "card": {    "suffix": "0580",    "expirationMonth": "12",    "expirationYear": "2023"  },  "metadata": {    "cardArt": {      "combinedAsset": {        "id": "d3225702-354a-4f17-8c40-1727de7ffa57",        "_links": {          "self": {            "href": "/tms/v2/tokens/7030000000042974378/mdes/assets/card-art-combined"          }        }      }    },    "issuer": {      "name": "METROBANK CARD CORPORATION (A FINANCE COMPANY)",      "shortDescription": "METROBANK CARD CORPORATION"    },    "creator": "testrest"  }}
FieldTypeDescription
card.numberSet to the tokenized card number. When source is set to TOKEN, this field value must be a digital network token to provision a COF network token.
card.expirationMonth
card.expirationYear
createInstrumentIdentifierSet to true.
sourceSet to TOKEN. The value set for card.number must be a digital network token to provision a COF network token.
consumerIdWhen this field is not included, a network token is provisioned only for the PAN in the request.
Optional Fields
FieldTypeDescription
card.securityCode

Provision a Network Token with Push Provisioning

This section describes how to provision a network token with push provisioning.

Push provisioning enables you to provision a network token directly to a consumer's device or digital wallet in a single transaction.

This workflow shows the process for push provisioning:

  1. The customer logs in to their bank account and chooses a card and merchant.
  2. The issuer sends the encrypted payment and user data to the network token provider.
  3. The network token provider sends the encrypted payment and user data to the issuer.
  4. The issuer invokes the merchant application with the token request push data.
  5. The customer registers for a merchant account or logs into an existing account.
  6. You decrypt the push data.
  7. You send a request to TMS to provision a network tokenized card.
  8. TMS sends a request to the network token provider to provision the tokenized card.
  9. The network token provider sends the provisioning response to TMS.
  10. TMS sends you the TMS token along with the provisioning status.
  11. Using the response sent from TMS, you send a request to TMS to retrieve the instrument identifier token.
  12. TMS sends you the instrument identifier token.
  13. You store the instrument identifier token for future transactions.

Endpoint

POST /tms/v2/tokenized-cards

POST /tms/v2/tokenized-cards

Card Art

This section describes how to retrieve card art for network tokens.

Card art includes images and metadata for displaying payment instrument information in digital wallets and on devices.

Retrieve Card Art

Retrieve card art assets for a network token, including combined card art, brand logo, issuer logo, and icon assets.

Endpoint

GET /tms/v2/tokens/{tokenId}/vts/assets/card-art-combined

GET /tms/v2/tokens/{tokenId}/vts/assets/card-art-combined

Example

{  "combinedAsset": {    "id": "8f64614def1a41d39ea8acae4616bf6f",    "_links": {      "self": {        "href": "/tms/v2/tokens/7031530000033441624/vts/assets/card-art-combined"      }    }  },  "brandLogoAsset": {    "id": "00000000000000000000000000001071",    "_links": {      "self": {        "href": "/tms/v2/tokens/7031530000033441624/vts/assets/brand-logo"      }    }  },  "foregroundColor": "1af0f0",  "backgroundColor": "009614",  "labelColor": "19550a"}

Simulate Lifecycle Management Events

This section describes how to simulate lifecycle management (LCM) events for network tokens in the sandbox environment.

LCM events represent state changes in the lifecycle of a network token, such as activation, deactivation, or renewal. Simulating these events enables you to test your integration handling of various token state scenarios.

Endpoint

POST /tms/v2/tokens/{tokenId}/lcm-events/simulate

POST /tms/v2/tokens/{tokenId}/lcm-events/simulate

Supported LCM Events

You can simulate these LCM event types:

  • Token activation
  • Token deactivation
  • Token renewal
  • Lost or stolen card
  • Issuer decline scenarios
  • Service unavailability

Network Token Provision Failures

This section provides information about network token provision failures and reason codes.

Failure Reason Codes

Reason CodeDescription
INVALID_REQUESTThe network token provision request contained invalid data.
CARD_VERIFICATION_FAILEDThe network token provision request contained data that could not be verified.
CARD_NOT_ELIGIBLEThe card cannot be used currently with the issuer for tokenization.
CARD_NOT_ALLOWEDThe card cannot be used currently with the card association for tokenization.
DECLINEDThe card cannot be used currently with the issuer for tokenization.
SERVICE_UNAVAILABLEThe network token service was unavailable or timed out.
SYSTEM_ERRORAn unexpected error occurred with the network token service. Check your configuration.

Lost and Stolen Card Response

{  "_links": {    "self": {      "href": "/tms/v1/instrumentidentifiers/7030000000041554452"    },    "paymentInstruments": {      "href": "/tms/v1/instrumentidentifiers/7030000000041554452/paymentinstruments"    }  },  "id": "7030000000041554452",  "object": "instrumentIdentifier",  "state": "ACTIVE",  "tokenizedCard": {    "state": "UNPROVISIONED",    "reason": "CARD_NOT_ELIGIBLE",    "type": "visa"  },  "card": {    "number": "400555XXXXXX4452"  },  "metadata": {    "creator": "testrest"  }}

Issuer Decline Response

{  "_links": {    "self": {      "href": "/tms/v1/instrumentidentifiers/7030000000051790079"    },    "paymentInstruments": {      "href": "/tms/v1/instrumentidentifiers/7030000000051790079/paymentinstruments"    }  },  "id": "7030000000051790079",  "object": "instrumentIdentifier",  "state": "ACTIVE",  "tokenizedCard": {    "state": "UNPROVISIONED",    "reason": "CARD_NOT_ALLOWED",    "type": "visa"  },  "card": {    "number": "462294XXXXXX0079"  },  "metadata": {    "creator": "testrest"  }}

Last published: September 29, 2026