You might be thinking what is token? In this API, the traditional PAN is replaced with a set of uniquely randomly generated digital sequences to protect the user's data, which is a Token.

A surrogate value for a PAN that is a 13 to 19-digit numeric value that must pass basic validation rules of an account number, including the Luhn check digit.Because the length and format of the Token and original Primary Account Number (PAN) are the same, the replacement card number does not affect the subsequent processing process, and when Token is used, instead of PAN, it can avoid directly exposing the user's actual account information, which is more secure.The replacement card number can also provide enhanced risk control, including restrictions on payment token usage by specific devices, merchants, or channels.

Here are some basic concepts related to this API:

Token Requestor (TR): An entity submitting Token Requests to the Token Service Provider. Each Payment Token Requestors may be traditional participants within the payments industry, or newly emerging participants. Potential Token Requestors include, but are not limited to:

3. Payment enablers, such as device original equipment manufacturer (OEM)

4. Digital wallet providers

5. Card issuers

Token Requestors will be required to register with Token Service Providers and comply with their proprietary registry requirements, systems, and processes. After successful registration with a Token Service Provider, the Token Requestor will be assigned a Token Requestor ID or multiple Token Requestor IDs for different Token Domains.

Token Service Provider (TSP): Token Service Providers are responsible for a number of discrete functions in their capacity as the authorized party for issuance of Payment Tokens. That is to say, it is the one that provides the token.

Token Service Providers are responsible for building and managing their own proprietary Token Requestor APIs, Token Vaults, Token provisioning platforms, and Token registries. Token Service Providers must ensure that Token BINs or Token BIN ranges are managed distinctly from traditional BINs or BIN ranges, in part to avoid any inadvertent overlap of PANs and Payment Tokens.

Key features

Payment Tokenization Solution has the following significant features:

1、Reduce the possibility of leakage of sensitive information, using token instead of actual card number avoid leaking card information; In addition, the scope of payment application in token were limited, to further reduce the influence scope of payment after token leaking.

2、With compatibility and interoperability, payment token can be processed normally in the transaction network like card numbers, and the application and transaction process of payment token can be done without perception among the cardholders.

3、Promote the development of industry innovation.

When to Use it?

1、It is applied to the big merchants 。In the merchant side (payment system)， using Token instead of the original card number can reduce the risk of the information leakage of the merchant end.

2、It is applied to digital wallet and professional payment gateway, providing payment solution for e-commerce platform and online merchants. Users can register at one time, and can be used in different businesses.

3、It is applied to QR code payment，The offline QR payment and bar code payment are used to solve the problem that the static code contains sensitive card number information.

4、It is applied to NFC application and offline contactless payment, It is used to solve the problem of card number information leakage without SE environment, and also to solve the problem of card number being abused in the environment of SE.

The following figure is the flow chart of the token service. TR is the developer,that is you，and TSP is the server of UnionpayIntl that provides token. The two APIs in the orange box are the APIs associated with the key exchange, primarily the MAC key for the exchange of signatures and the enc key for encryption; After key exchange, you can start to request token, three red box is the API related to token, the first box is API to request token, the second box used to update token state, the third box used for detoken.

APIs Included

APIs Included

Key Exchange

Key Reset

Token Request

Token Key Request

Token Status Update

De-Tokenize Request

Interface description

This is the key exchange message from TSP to the TR.This key is used for signature verification.

Request Method

HTTP GET

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Message Information

msgInfo

object

M-Must

Version Number

versionNo

ANS

5

M-Must

Valid Value: "1.0.0"

Message ID

msgId

AN

20-25

M-Must

243 It is used to match a response to its request. The value must uniquely identify any message that the TR initiates on any day. The value in response must match the value in the request.

System Trace Audit Number must be unique for each Token Requestor on the same day .

Retrieval Reference Number

SysRefNo

N

12

M-Must

Generated by TSP System in the response message to TR.

Transmission Date and Time

TranDtTm

N

10

R-Return

Generated by TR according to GMT+8 time zone in the request message and filled by TSP System with the same value in response message . Format: MMDDhhmmss

Local Transaction Date and Time

LocalDtTm

N

10

R-Return

Generated by TR according to local time zone in the request message and filled by TSP System with the same value in response message . Format: MMDDhhmmss

TRID

TrId

N

11

R-Return

Response Code

rspCd

AN

2

M-Must

Response Information

RspMsg

ANS

1-256

M-Must

Detailed information for response code.

MAC

mac

ANS

16

M-Must

Interface description

When TR requests Token from TSP, the TSP will implement appropriate Token Domain Restriction Controls, generate the Token Assurance Level according to the ID&V result, and respond to TR with a Token. When TR sends Token request for the same card number and same usage scenario again, TSP will approve the request and respond with the previous Token and related information in Token Vault.

Request Method

HTTP POST

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Message Information

msgInfo

object

M-Must

Version Number

versionNo

ANS

5

M-Must

Valid Value: "1.0.0"

Message ID

msgId

AN

20-25

M-Must

It is used to match a response to its request. The value must uniquely identify any message that the TR initiates on any day. The value in response must match the value in the request.

System Trace Audit Number must be unique for each Token Requestor on the same day.

Transmission Date and Time

TranDtTm

N

10

M-Must

Format : MMDDhhmmss. Generated by TR according to GMT+8 time zone in the request message and filled by TSP System with the same value in response message . Format: MMDDhhmmss

Local Transaction Date and Time

LocalDtTm

N

10

M-Must

Format : MMDDhhmmss. Generated by TR according to local time zone in the request message and filled by TSP System with the same value in response message . Format: MMDDhhmmss

TRID

TrId

N

11

M-Must

Primary Account Number

PriAcct

AN

8-16

M-Must

Card Number encrypted with Encryption Key in Key Exchange Message with the following padding: (1) If the length of PAN with panType is odd, append ‘F’ to the PAN. (2) Append 80 follow by 00 until the length of PAN in hexadecimal binary is multiple of 8 bytes. There must be at least one padding even if the PAN is already 8 bytes of length. (3) The padded data will be encrypted with the Encryption Key exchanged in Key Change message in Section "Error! Reference source not found". using triple DES.

Requested Token Effective Period

TokenExpr

N

12

M-Must

Format : YYMMDDhhmmss. In Token request message and Token information update message, this field indicates the Requested Token Effective Period. But the effective period will eventually be determined by the TSP. Format: YYMMDDhhmmss

Single Transaction Limit

TranLmt

N

12

O-Optional

The maximum transaction amount of this Token is for one transaction .

Terminal Type Bitmap

ChnlBit

N

7

M-Must

Valid Values: 0: indicates that the Token must not be used in the terminal type ; 1: indicates that the Token can be used in the terminal .

Single Tran Limit Currency Code

TranLmtCur

N

3

O-Optional

Only for TR outside of Mainland China.

List of Merchant Codes

ListMID

AN

15-159

O-Optional

List of 15-digit alphanumeric merchant ID separated by “,”. Up to 10 merchant IDs in the list.

Valid Values: 01: Remote storage: An example would be a card-on-file database ; 02: SE storage: An example would be UPI approved secure element in mobile phone/IC card ; 03: Local Device storage: An example would be Payment Token data stored using the standard data storage mechanisms of a consumer controlled device ; 04: Local hardware secured storage: An example would be using a Trusted Execution Environment to ensure appropriately restricted access to data ; 05-99: Reserved for future use .

System Trace Audit Number must be unique for each Token Requestor on the same day .

Retrieval Reference Number

SysRefNo

N

12

M-Must

Generated by TSP System in the response message to TR.

Terminal Type Bitmap

ChnlBit

N

7

M-Must

The terminal type bitmap indicates if the Token can be used in the terminal type. Valid Values: 0: indicates that the Token must not be used in the terminal type ; 1: indicates that the Token can be used in the terminal .

Transmission Date and Time

TranDtTm

N

10

R-Return

Format : MMDDhhmmss. Generated by TR according to GMT+8 time zone in the request message and filled by TSP System with the same value in response message . Format: MMDDhhmmss

Local Transaction Date and Time

LocalDtTm

N

10

R-Return

Format : MMDDhhmmss. Generated by TR according to local time zone in the request message and filled by TSP System with the same value in response message . Format: MMDDhhmmss

TRID

TrId

N

11

R-Return

Requested Token Effective Period

TokenExpr

N

12

R-Return

Format : YYMMDDhhmmss. In Token request message and Token information update message, this field indicates the Requested Token Effective Period. But the effective period will eventually be determined by the TSP. Eg: the value ‘010101010101’ of this field indicates the expected effective period to be 1 year, 1 month, 1 day, 1 hour, 1 minute, and 1 second. One year indicates 365 days and one month indicates 30 days. Format: YYMMDDhhmmss

Single Transaction Limit

TranLmt

N

12

R-Return

The maximum transaction amount of this Token is for one transaction .

Single Transaction Limit Cur Code

TranLmtCur

N

3

R-Return

Only used in the token request from TR outside of Mainland China.

List of Merchant Codes

ListMID

AN

15-159

R-Return

List of 15-digit alphanumeric merchant ID separated by “,”. Up to 10 merchant IDs in the list.

Valid Values: 01: Remote storage: An example would be a card-on-file database ; 02: SE storage: An example would be UPI approved secure element in mobile phone/IC card ; 03: Local Device storage: An example would be Payment Token data stored using the standard data storage mechanisms of a consumer controlled device ; 04: Local hardware secured storage: An example would be using a Trusted Execution Environment to ensure appropriately restricted access to data ; 05-99: Reserved for future use .

Transaction Medium

TranMedium

AN

1

R-Return

Token ID

TokenId

N

1-10

C-Condition

The unique identifier of the token

Token PAN

TokenPAN

N

13-19

C-Condition

The PAN for the Token. Present when response code is 00.

Payment Account Reference

par

AN

1-29

C-Condition

Present when response code is 00.

Assigned Token Assurance Level

TkSecLvl

N

1-2

C-Condition

Generated by TSP according to TSP evaluation of the Token. Valid Values:0~99 .

Card Number encrypted with Encryption Key in Key Exchange Message with the following padding: (1) If the length of PAN with panType is odd, append ‘F’ to the PAN. (2) Append 80 follow by 00 until the length of PAN in hexadecimal binary is multiple of 8 bytes. There must be at least one padding even if the PAN is already 8 bytes of length. (3) The padded data will be encrypted with the Encryption Key exchanged in Key Change message in Section "Error! Reference source not found". using triple DES.

The requested Token effective period in Token Request message is outside the Token Requestor’s Domain Control

22

The maximum Token usage number in Token Request message is outside the Token Requestor’s Domain Control

23

The single transaction limit in Token Request message is outside the Token Requestor’s Domain Control

24

The Token Assurance level is outside the Token Requestor’s Domain Control

30

Format error

40

TR is not allowed to perform this transaction

41

Suspended Token

51

Temporary token which is not allowed to update token information or token status, and etc.

96

System error

Concept Description

Concept Description

De-tokenization: The process of redeeming a Payment Token for its associated PAN value based on the Payment Token to PAN mapping, whilst performing required verification of the Payment Token and enforcing the Token Domain Restriction Controls associated with the Payment Token.

Identification and Verification: A valid method through which an entity may successfully validate the Cardholder and the Cardholder’s account in order to establish a confidence level for Payment Token to PAN /Cardholder binding.

Payment Token: A surrogate value for a PAN that is a 13 to 19-digit numeric value that must pass basic validation rules of an account number, including the Luhn check digit. The Payment Token number is passed in lieu of the PAN and the Token Expiry Date is passed in lieu of the PAN Expiry Date to improve transaction security in a message.

Token Assurance Level: A value that allows the Token Service Provider to indicate the confidence level of the Payment Token to PAN / Cardholder binding. It is determined as a result of the type of Identification and Verification (ID&V) performed and the entity that performed it. It may also be influenced by additional factors such as the Token Location. The Token Assurance Level is set when issuing a Payment Token and may be updated if additional ID&V is performed. The Token Assurance Level value is defined by the Token Service Provider.

Token BIN: A specific BIN or range within a BIN that has been designated only for the purpose of issuing Payment Tokens and is flagged accordingly in BIN tables.

Token Domain: The types of transactions for which a Payment Token may be used. Token Domains may be channel-specific (e.g., NFC only), merchant-specific, digital wallet-specific, or a combination of any of the above.

Token Location: An indication of the intended mode of storage for a Payment Token and any related data, provided by a Token Requestor when requesting a Payment Token from a Token Service Provider. The security of this location may influence the Token Assurance Level that can be assigned to a Payment Token. Due diligence of the security provided by Token Requestors is the responsibility of Token Service Provider and assignation of a location type to Token Requestor will be at the discretion of Token Service Provider. Currently identified location types are: 1. Remote storage: An example would be a card-on-file database. 2. SE storage: An example would be UPI approved secure element in mobile phone / IC card. 3. Local Device storage: An example would be Payment Token data stored using the standard data storage mechanisms of a consumer controlled device. 4. Local hardware secured storage: An example would be using a Trusted Execution Environment to ensure restricted access to data. 5.Remote hardware secured storage: An example would be using Cloud-based payment. More storage locations may be added over time.