Open API >Payment >Token Service
Token Service
Payment Developer Acquirer Issuer
This API is Token service Interface. It includes the interface between Token Requestor and Token Service Provider for Token request, update, life management, and etc.
API Introduction
API Introduction
What is it?

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: 

1. Card-On-File merchants 

2. Acquirers, acquirer processors, and payment gateways on behalf of merchants 

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.

Who Use it?
Potential Token Requestors include, but are not limited to: 1、Card-On-File merchants ; 2、Payment enablers, such as device original equipment manufacturer (OEM) ; 3、Digital wallet providers ; 4、Card issuers.
Where to Use it?
This API is available globally except for mainland China
Flow Chart
Flow Chart

    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.

Token Service流程图-新.png

API Document
API Document
  • 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.
Message Type msgType ANS 2 M-Must Valid Value: "20" : Token Request; "21" : Token Key Request; "23" : Token Status Update; "24" : De-Token Request; "80" : Key Exchange; "81" : Key Reset.
System Trace Audit Number TransSsn N 8 M-Must System Trace Audit Number must be unique for each Token Requestor on the same day .
Transmission Date and Time TranDtTm N 10 M-Must 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 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
MAC Key MACKey ANS 32 M-Must Encrypted 32 hexadecimal double length 3DES key encrypted with 3DES CBC using KEK.
Encryption Key ENCKey ANS 32 M-Must Encrypted 32 hexadecimal double length 3DES key encrypted with 3DES CBC using KEK.
MAC mac ANS 16 M-Must
Synchronous Response parameters
Filed 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.
Message Type msgType ANS 2 M-Must Valid Value: "20" : Token Request; "21" : Token Key Request; "23" : Token Status Update; "24" : De-Token Request; "80" : Key Exchange; "81" : Key Reset.
System Trace Audit Number TransSsn N 8 R-Return 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
Response Code Reference
Response Code Reference
Response code Description
00 Completed successfully
01 Invalid TR status
02 Invalid Token status
05 The merchant does not support this business
06 Invalid amount
08 Invalid terminal type
09 Invalid TRID
10 The public key of TR is not found
11 Signature verification failed
12 Sensitive information decryption failed
13 Expired Token
14 Invalid Token
16 Restricted Merchant Range
18 The token does not belong to the TR
21 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.


  • Contact Us
  • If you have any further questions, please register and submit order in your user center.