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:
| Feature | Instrument identifier token | Network token |
|---|---|---|
| Generated by | The TMS token vault | The card network scheme |
| Contains | The tokenized PAN for card payments, or a US or Canadian bank account and routing number | A network-generated value that replaces the PAN during transaction processing |
| Detokenized by | TMS, which sends the PAN to the issuer for authorization | The payment network or the issuer |
| Mapping | Holds the associated network token | Mapped to an instrument identifier token |
| Minimum data to create | The account number being tokenized | The PAN and the expiration date |
| Customer-initiated transactions | The token in the request | The token and a cryptogram |
| Authorization rates | Standard | Improved 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
PCIscope: 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
- The customer enters their card data and sends the PAN to the merchant.
- The merchant sends the PAN to Token Management Service.
- Token Management Service generates a TMS token and synchronously provisions a network token from the card brand.
- Token Management Service sends the merchant the TMS token, expiration date, suffix, and
payment account reference(PAR). - The merchant stores the TMS token ID and network token flag and sends the customer the masked card number.
Cryptogram Retrieval
- The merchant requests the cryptogram using a TMS token from Token Management Service.
- Token Management Service looks up the network token and sends the token metadata to the card brand.
- The card brand generates the cryptogram and sends it to Token Management Service.
- Token Management Service sends the network token and cryptogram to the merchant.
- The merchant uses the network token along with the cryptogram to start the authorization.
PAR Retrieval
- The merchant retrieves the TMS token and sends to Token Management Service.
- Token Management Service looks up the token and retrieves the PAR.
- Token Management Service sends the PAR to the merchant.
- The merchant stores the PAR.
Partner Model: Network Token Provisioning
This workflow shows the process of network token provisioning for partners.
Tokenizing PAN
- The customer enters their card data and sends the PAN to the merchant.
- The merchant sends the PAN to Token Management Service.
- Token Management Service generates a TMS token and synchronously provisions a network token from the card brand.
- Token Management Service sends the merchant the TMS token, expiration date, suffix, and payment account reference (PAR).
- The merchant stores the TMS token ID and network token flag and sends the customer the masked card number.
Cryptogram Retrieval
- The merchant requests the payment credentials using a TMS token from Token Management Service.
- Token Management Service looks up the network token and sends the token metadata to the card brand.
- The card brand generates the cryptogram and sends it to Token Management Service.
- Token Management Service sends the network token and cryptogram to the merchant.
- The merchant uses the network token along with the cryptogram to start the authorization.
PAR Retrieval
- The merchant retrieves TMS token and sends it to Token Management Service.
- Token Management Service looks up the token and retrieves the PAR.
- Token Management Service sends the PAR to the merchant.
- The merchant stores the PAR.
Endpoints
Tokenized Cards
| Method | Path | Description | |
|---|---|---|---|
POST | /tms/v2/tokenized-cards | Provision 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
| Method | Path | Description | |
|---|---|---|---|
POST | /tms/v2/tokens/{tokenId}/payment-credentials | Generate standard payment credentials | |
POST | /tms/v2/tokens/{tokenId}/payment-credentials-dcap | Generate DCAP payment credentials | |
POST | /tms/v2/tokens/{tokenId}/payment-credentials-vpp | Generate payment passkey credentials |
Payments and Transactions
| Method | Path | Description | |
|---|---|---|---|
POST | /pts/v2/payments | Authorize a payment (with or without network token) | |
PATCH | /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId} | Update merchant-initiated transaction (MIT) authorization options |
Card Art
| Method | Path | Description | |
|---|---|---|---|
GET | /tms/v2/tokens/{tokenId}/vts/assets/card-art-combined | Retrieve card art |
Lifecycle Management
| Method | Path | Description | |
|---|---|---|---|
POST | /tms/v2/tokens/{tokenId}/lcm-events/simulate | Simulate 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"}| Field | Type | Description |
|---|---|---|
card.number | string | The card number. |
card.expirationMonth | string | The expiration month of the card in two-digit format (MM). For example, 12. |
card.expirationYear | string | The expiration year of the card in four-digit format (YYYY). For example, 2026. |
source | string | Set 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--06oPOwStep 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:
| Field | Type | Description |
|---|---|---|
paymentInformation.tokenizedCard.number | string | The network token value that you received from the token service provider. |
paymentInformation.tokenizedCard.expirationMonth | string | The token expiration month that you received from the token service provider. |
paymentInformation.tokenizedCard.expirationYear | string | The token expiration year that you received from the token service provider. |
paymentInformation.tokenizedCard.cryptogram | string | The 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):
- The customer makes a purchase and selects COF.
- The merchant submits an authorization to the payment processor using a TMS token.
- The payment processor uses the TMS token to look up the network token.
- The payment processor requests the cryptogram generated by the card brand.
- The payment processor sends the network token, cryptogram, and
3-D Securedata to the acquirer in the authorization request. - The acquirer processes the authorization and sends the authorization result to the payment processor.
- The payment processor sends the authorization result to the merchant.
- 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).
- The merchant sends the TMS token to the payment processor.
- The payment processor looks up the network token associated with the TMS token.
- The payment processor sends the network token and MIT COF data to the acquirer in the authorization request.
- The acquirer processes the authorization and sends the authorization result to the payment processor.
- The payment processor sends the authorization result to the merchant.
- The merchant updates the system to reflect the status of the transaction.
- 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.
- The customer makes a purchase and selects COF.
- The merchant requests the payment credentials and sends the TMS token to the payment processor.
- The payment processor uses the TMS token to look up the network token.
- The payment processor requests the cryptogram generated by the card brand.
- The payment processor sends the network token and cryptogram to the merchant.
- The merchant uses the network token along with the cryptogram to start the authorization.
- The merchant sends the network token, cryptogram, and 3-D Secure data to the acquirer in the authorization request.
- The acquirer processes the authorization and sends the authorization result to the merchant.
- 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).
- The merchant requests the payment credentials and sends the TMS token to the payment processor.
- The payment processor uses the TMS token to look up the network token.
- The payment processor sends the network token and cryptogram to the merchant.
- The merchant uses the network token along with the cryptogram to start the authorization.
- The merchant sends the network token and MIT COF data to the acquirer in the authorization request.
- The acquirer processes the authorization and sends the authorization result to the merchant.
- 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"}| Field | Type | Description |
|---|---|---|
clientReferenceInformation.code | ||
paymentInformation.customer.id | ||
paymentInformation.paymentInformation.id | ||
paymentInformation.shippingAddress.id | ||
orderInformation.amountDetails.currency | ||
orderInformation.amountDetails.totalAmount | ||
processingInformation.capture | ||
processingInformation.commerceIndicator | ||
tokenInformation.networkTokenOption | Set 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" }}| Field | Type | Description |
|---|---|---|
card.number | ||
card.expirationMonth | ||
card.expirationYear | ||
createInstrumentIdentifier | Set to true. | |
source | Set to ONFILE. | |
consumerId | When this field is not included, a network token is provisioned only for the PAN in the request. |
Optional Fields
| Field | Type | Description |
|---|---|---|
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" }}| Field | Type | Description |
|---|---|---|
card.number | Set 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 | ||
createInstrumentIdentifier | Set to true. | |
source | Set to TOKEN. The value set for card.number must be a digital network token to provision a COF network token. | |
consumerId | When this field is not included, a network token is provisioned only for the PAN in the request. |
Optional Fields
| Field | Type | Description |
|---|---|---|
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:
- The customer logs in to their bank account and chooses a card and merchant.
- The issuer sends the encrypted payment and user data to the network token provider.
- The network token provider sends the encrypted payment and user data to the issuer.
- The issuer invokes the merchant application with the token request push data.
- The customer registers for a merchant account or logs into an existing account.
- You decrypt the push data.
- You send a request to TMS to provision a network tokenized card.
- TMS sends a request to the network token provider to provision the tokenized card.
- The network token provider sends the provisioning response to TMS.
- TMS sends you the TMS token along with the provisioning status.
- Using the response sent from TMS, you send a request to TMS to retrieve the instrument identifier token.
- TMS sends you the instrument identifier token.
- 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 Code | Description |
|---|---|
INVALID_REQUEST | The network token provision request contained invalid data. |
CARD_VERIFICATION_FAILED | The network token provision request contained data that could not be verified. |
CARD_NOT_ELIGIBLE | The card cannot be used currently with the issuer for tokenization. |
CARD_NOT_ALLOWED | The card cannot be used currently with the card association for tokenization. |
DECLINED | The card cannot be used currently with the issuer for tokenization. |
SERVICE_UNAVAILABLE | The network token service was unavailable or timed out. |
SYSTEM_ERROR | An 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" }}Thanks for your feedback!
Last published: September 29, 2026