Payment
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.
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.
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.
| Field name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | Valid Value: "20" : Token Request; "21" : Token Key Request; "23" : Token Status Update; "24" : De-Token Request; "80" : Key Exchange; "81" : Key Reset. | ||
| MAC | mac | ANS | 16 | M:Mandatory | |||
| System Trace Audit Number | TransSsn | N | 8 | M:Mandatory | System Trace Audit Number must be unique for each Token Requestor on the same day. | ||
| Transmission Date and Time | TranDtTm | N | 10 | M:Mandatory | 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:Mandatory | 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:Mandatory | |||
| Primary Account Number | PriAcct | AN | 8-16 | M:Mandatory | 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:Mandatory | 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:Mandatory | 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. | ||
| Transaction Channel | TranChan | AN | 2 | O:Optional | 2 digit transaction channel code: 00 – Unknown； 01 – ATM； 02 – RFU； 03 – POS； 04 – RFU； 05 – Multi-media End Point； 06 – Counter ； 07 – PC； 08 – Mobile Phone； 09 – Phone (Type I)； 10 – RFU； 11 – Mobile POS； 12 – CUP Customer Service； 13 – Farmer Bank Card Special Service； 14 – Merchant System； 15 – 3rd Party System； 16 – Set Top Box； 17 – Phone (Type II)； 18 – RFU； 19 – RFU； 20 – Document Management System； 21 – RFU； 22 – RFU； 23 - MPOS | ||
| Transaction Initiation | TranInit | AN | 1 | O:Optional | 1 digit transaction initiation code : 0 – Unknown ; 1 - Attended ; 2 – Unattended ; 3 – Agent ; 4 – Batch Agent ; 5 – Delayed Authorization Unattended ; 6 – Delayed Authorization Attended. | ||
| Transaction Medium | TranMedium | AN | 1 | O:Optional | 1 digit transaction medium code : 0 – Unknown ; 1 – Magnetic Stripe Card Transaction ; 2 – Chip Card Transaction ; 3 – Magnetic Stripe Hybrid Transaction ; 4 – Virtual Card Transaction ; 5 – Manual Input Transaction ; 6 – Biological Traits Transaction ; 7 – Card Not Present Transaction. | ||
| Cardholder Id Ver Result | ValResult | string | 1-2048 | M:Mandatory | Fill the cardholder result as follows: {ID type verification result|ID number verification result|Cardholder name verification result | Mobile number verification result | Dynamic code verification result|PIN verification result | CVN2 verification result | Expiry Date verification result} . | ||
| Token Location | TokenStore | N | 2 | M:Mandatory | 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 . | ||
| SEID | SeId | ANS | 1-64 | C:Conditional | Security Element ID number . | ||
| Token Usage Scenario Id | TkSubTpId | N | 2 | M:Mandatory | Provided by TR Valid Values: 01: SE ; 02: HCE ; 03: QR code ; 04: Card-On-File (COF) ; 05: Digital wallet ; 06: Chip or Magstripe Card . | ||
| Product Identification | ProdId | ANS | 4 | C:Conditional | 1.Filled by TR in the Token request. The first byte indicates the product category and the last 3 bytes indicate the product sub-category. 2. Base64 encoding the entire field . |
| Filed name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | Valid Value: "20" : Token Request; "21" : Token Key Request; "23" : Token Status Update; "24" : De-Token Request; "80" : Key Exchange; "81" : Key Reset. | ||
| MAC | mac | ANS | 16 | M:Mandatory | |||
| System Trace Audit Number | TransSsn | N | 8 | R:Returned | System Trace Audit Number must be unique for each Token Requestor on the same day . | ||
| Retrieval Reference Number | SysRefNo | N | 12 | M:Mandatory | Generated by TSP System in the response message to TR. | ||
| Terminal Type Bitmap | ChnlBit | N | 7 | M:Mandatory | 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:Returned | 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:Returned | 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:Returned | |||
| Requested Token Effective Period | TokenExpr | N | 12 | R:Returned | 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:Returned | The maximum transaction amount of this Token is for one transaction . | ||
| Single Transaction Limit Cur Code | TranLmtCur | N | 3 | R:Returned | Only used in the token request from TR outside of Mainland China. | ||
| List of Merchant Codes | ListMID | AN | 15-159 | R:Returned | List of 15-digit alphanumeric merchant ID separated by “,”. Up to 10 merchant IDs in the list. | ||
| Transaction Channel | TranChan | AN | 2 | R:Returned | 00 – Unknown； 01 – ATM； 02 – RFU； 03 – POS； 04 – RFU； 05 – Multi-media End Point； 06 – Counter ； 07 – PC； 08 – Mobile Phone； 09 – Phone (Type I)； 10 – RFU； 11 – Mobile POS； 12 – CUP Customer Service； 13 – Farmer Bank Card Special Service； 14 – Merchant System； 15 – 3rd Party System； 16 – Set Top Box； 17 – Phone (Type II)； 18 – RFU； 19 – RFU； 20 – Document Management System； 21 – RFU； 22 – RFU； 23 - MPOS | ||
| Transaction Initiation | TranInit | AN | 1 | R:Returned | 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:Returned | |||
| Token ID | TokenId | N | 1-10 | C:Conditional | The unique identifier of the token | ||
| Token PAN | TokenPan | string | 13-19 | C:Conditional | The PAN for the Token. Present when response code is 00. | ||
| Payment Account Reference | PAR | string | 1-29 | C:Conditional | Present when response code is 00. | ||
| Assigned Token Assurance Level | TkSecLvl | N | 1-2 | C:Conditional | Generated by TSP according to TSP evaluation of the Token. Valid Values:0~99 . | ||
| Token Effective Time | TokenBegin | N | 14 | C:Conditional | Generated according to GMT+8 time zone . Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss | ||
| Token Expiry Time | TokenEnd | N | 14 | C:Conditional | Generated according to GMT+8 time zone. The Token Expiry Date is the 3rd-6th digits of Token Expiry Time. Format : YYYYMMDDhhmmss. Format: YYYYMMDDhhmmss | ||
| PAN Suffix | PanSuffix | ANS | 4 | C:Conditional | The last 4 digits of PAN . | ||
| Response Code | RspCd | AN | 2 | M:Mandatory | |||
| Response Information | RspMsg | ANS | 1-256 | M:Mandatory | Detailed information for response code. |
| Field name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | Valid Value: "20" : Token Request; "21" : Token Key Request; "23" : Token Status Update; "24" : De-Token Request; "80" : Key Exchange; "81" : Key Reset. | ||
| MAC | mac | ANS | 16 | M:Mandatory | |||
| System Trace Audit Number | TransSsn | N | 8 | M:Mandatory | System Trace Audit Number must be unique for each Token Requestor on the same day . | ||
| Transmission Date and Time | TranDtTm | N | 10 | M:Mandatory | 10 | 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:Mandatory | 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:Mandatory | |||
| TokenID | TokenId | N | 1-10 | C:Conditional | The unique identifier of the token. | ||
| Token PAN | TokenPAN | N | 13-19 | C:Conditional | Either Token ID or Token PAN is mandatory . | ||
| Num of Keys | TokenKeyNo | N | 2 | C:Conditional | Only if Key Type is LMK. Number of keys to download, maximum is 10. | ||
| Key Type | TokenKeyType | AN | 3 | M:Mandatory | Either “CMK” or “LMK”. | ||
| Key TTL | TokenTTL | string | 5 | C:Conditional | Time to live of the LMK Token Key in minutes. |
| Filed name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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 | M:Mandatory | 2 | Valid Value: "20" : Token Request; "21" : Token Key Request; "23" : Token Status Update; "24" : De-Token Request; "80" : Key Exchange; "81" : Key Reset. | ||
| MAC | mac | ANS | 16 | M:Mandatory | |||
| System Trace Audit Number | TransSsn | N | 8 | R:Returned | System Trace Audit Number must be unique for each Token Requestor on the same day . | ||
| Retrieval Reference Number | SysRefNo | N | 12 | M:Mandatory | |||
| Transmission Date and Time | TranDtTm | N | 10 | R:Returned | 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:Returned | 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:Returned | |||
| Token ID | TokenId | N | 1-10 | R:Returned | The unique identifier of the token. | ||
| Token PAN | TokenPAN | N | 13-19 | R:Returned | |||
| Num of Keys | TokenKeyNo | N | 2 | R:Returned | Number of keys to download, maximum is 10. | ||
| Key Type | TokenKeyType | AN | 3 | R:Returned | Either “CMK” or “LMK”. | ||
| Key TTL | TokenTTL | string | 5 | R:Returned | Time to live of the LMK Token Key in minutes. | ||
| List of Merchant Codes | TokenKeyList | AN | 15-159 | R:Returned | List of 15-digit alphanumeric merchant ID separated by “,”. Up to 10 merchant IDs in the list. | ||
| Response Code | RspCd | AN | 2 | M:Mandatory | |||
| Response Information | RspMsg | ANS | 1-256 | M:Mandatory | Detailed information for response code. |
| Field name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | 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:Mandatory | System Trace Audit Number must be unique for each Token Requestor on the same day . | ||
| Transmission Date and Time | TranDtTm | N | 10 | M:Mandatory | 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:Mandatory | 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:Mandatory | |||
| MAC Key | MACKey | ANS | 32 | M:Mandatory | Encrypted 32 hexadecimal double length 3DES key encrypted with 3DES CBC using KEK. | ||
| Encryption Key | ENCKey | ANS | 32 | M:Mandatory | Encrypted 32 hexadecimal double length 3DES key encrypted with 3DES CBC using KEK. | ||
| MAC | mac | ANS | 16 | M:Mandatory |
| Filed name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | 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:Returned | System Trace Audit Number must be unique for each Token Requestor on the same day . | ||
| Retrieval Reference Number | SysRefNo | N | 12 | M:Mandatory | Generated by TSP System in the response message to TR。 | ||
| Transmission Date and Time | TranDtTm | N | 10 | R:Returned | 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:Returned | 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:Returned | |||
| Response Code | RspCd | AN | 2 | M:Mandatory | |||
| Response Information | RspMsg | ANS | 1-256 | M:Mandatory | Detailed information for response code. | ||
| MAC | mac | ANS | 16 | M:Mandatory |
| Field name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | 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:Mandatory | System Trace Audit Number must be unique for each Token Requestor on the same day. | ||
| Transmission Date and Time | TranDtTm | N | 10 | M:Mandatory | 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:Mandatory | 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:Mandatory | |||
| MAC | mac | ANS | 16 | M:Mandatory |
| Filed name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | 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:Returned | System Trace Audit Number must be unique for each Token Requestor on the same day . | ||
| Retrieval Reference Number | SysRefNo | N | 12 | M:Mandatory | Generated by TSP System in the response message to TR. | ||
| Transmission Date and Time | TranDtTm | N | 10 | R:Returned | 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:Returned | 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:Returned | |||
| Response Code | respCd | string | 2 | M:Mandatory | |||
| Response Information | RspMsg | ANS | 1-256 | M:Mandatory | Detailed information for response code. | ||
| MAC | mac | ANS | 16 | M:Mandatory |
| Field name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | 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:Mandatory | System Trace Audit Number must be unique for each Token Requestor on the same day. | ||
| Transmission Date and Time | TranDtTm | N | 10 | M:Mandatory | 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:Mandatory | 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:Mandatory | |||
| Token ID | TokenId | N | 1-10 | C:Conditional | The unique identifier of the token. | ||
| Token PAN | TokenPAN | N | 13-19 | C:Conditional | The PAN for the Token, Either Token ID or Token PAN is mandatory. | ||
| Token Status | TokenSt | N | 1 | M:Mandatory | Valid Values: 1: Activated ; 2: Suspended ; 3: Unlinked . | ||
| MAC | mac | ANS | 16 | M:Mandatory |
| Filed name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | 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:Returned | System Trace Audit Number must be unique for each Token Requestor on the same day . | ||
| Retrieval Reference Number | SysRefNo | N | 12 | M:Mandatory | |||
| Transmission Date and Time | TranDtTm | N | 10 | R:Returned | 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:Returned | 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:Returned | |||
| Token ID | TokenId | N | 1-10 | R:Returned | The unique identifier of the token. | ||
| Token PAN | TokenPAN | N | 13-19 | R:Returned | The PAN for the Token. | ||
| Token Status | TokenSt | N | 1 | R:Returned | Valid Values: 1: Activated ; 2: Suspended ; 3: Unlinked . | ||
| Response Code | respCd | string | 2 | M:Mandatory | |||
| Response Information | respMsg | ANS | 1-256 | M:Mandatory | Detailed information for response code. | ||
| MAC | mac | ANS | 16 | M:Mandatory |
| Field name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | 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:Mandatory | System Trace Audit Number must be unique for each Token Requestor on the same day. | ||
| Transmission Date and Time | TranDtTm | N | 10 | M:Mandatory | 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:Mandatory | 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:Mandatory | |||
| Token ID | TokenId | N | 1-10 | C:Conditional | Either Token ID or Token PAN is mandatory. Present in response if response = “00”. The unique identifier of the token. | ||
| Token PAN | TokenPAN | N | 13-19 | C:Conditional | Either Token ID or Token PAN is mandatory . Present in response if response = “00”. | ||
| Transaction Amount | TranAmt | N | 12 | O:Optional | Transaction amount for domain restriction. | ||
| Transaction Currency | TranCur | string | 3 | O:Optional | Transaction currency for domain restriction. | ||
| Merchant ID | MID | AN | 15 | O:Optional | Merchant ID for domain restriction. | ||
| Transaction Channel | TranChan | AN | 2 | O:Optional | 2 digit transaction channel code: 00 – Unknown； 01 – ATM； 02 – RFU； 03 – POS； 04 – RFU； 05 – Multi-media End Point； 06 – Counter ； 07 – PC； 08 – Mobile Phone； 09 – Phone (Type I)； 10 – RFU； 11 – Mobile POS； 12 – CUP Customer Service； 13 – Farmer Bank Card Special Service； 14 – Merchant System； 15 – 3rd Party System； 16 – Set Top Box； 17 – Phone (Type II)； 18 – RFU； 19 – RFU； 20 – Document Management System； 21 – RFU； 22 – RFU； 23 - MPOS. | ||
| Transaction Initiation | TranInit | AN | 1 | O:Optional | 1 digit transaction initiation code : 0 – Unknown ; 1 - Attended ; 2 – Unattended ; 3 – Agent ; 4 – Batch Agent ; 5 – Delayed Authorization Unattended ; 6 – Delayed Authorization Attended. | ||
| Transaction Medium | TranMedium | AN | 1 | O:Optional | 1 digit transaction medium code : 0 – Unknown ; 1 – Magnetic Stripe Card Transaction ; 2 – Chip Card Transaction ; 3 – Magnetic Stripe Hybrid Transaction ; 4 – Virtual Card Transaction ; 5 – Manual Input Transaction ; 6 – Biological Traits Transaction ; 7 – Card Not Present Transaction. | ||
| MAC | mac | ANS | 16 | M:Mandatory |
| Filed name | Identifier | Type | Length | Request | Default value | Note | |
|---|---|---|---|---|---|---|---|
| Message Information | msgInfo | object | M:Mandatory | ||||
| Version Number | versionNo | ANS | 5 | M:Mandatory | Valid Value: "1.0.0". | ||
| Message ID | msgId | string | 20-25 | M:Mandatory | 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:Mandatory | 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:Returned | System Trace Audit Number must be unique for each Token Requestor on the same day . | ||
| Retrieval Reference Number | SysRefNo | N | 12 | M:Mandatory | Generated by TSP System in the response message to TR. | ||
| Transmission Date and Time | TranDtTm | N | 10 | R:Returned | 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:Returned | 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:Returned | |||
| Token ID | TokenId | N | 1-10 | R:Returned | Either Token ID or Token PAN is mandatory. Present in response if response = “00”. The unique identifier of the token. | ||
| Token PAN | TokenPAN | N | 13-19 | R:Returned | Either Token ID or Token PAN is mandatory. Present in response if response = “00”. | ||
| Transaction Amount | TranAmt | N | 12 | R:Returned | Transaction amount for domain restriction. | ||
| Transaction Currency | TranCur | string | 3 | R:Returned | Transaction currency for domain restriction. | ||
| Merchant ID | MID | AN | 15 | R:Returned | |||
| Transaction Channel | TranChan | AN | 2 | R:Returned | 2 digit transaction channel code: 00 – Unknown； 01 – ATM； 02 – RFU； 03 – POS； 04 – RFU； 05 – Multi-media End Point； 06 – Counter ； 07 – PC； 08 – Mobile Phone； 09 – Phone (Type I)； 10 – RFU； 11 – Mobile POS； 12 – CUP Customer Service； 13 – Farmer Bank Card Special Service； 14 – Merchant System； 15 – 3rd Party System； 16 – Set Top Box； 17 – Phone (Type II)； 18 – RFU； 19 – RFU； 20 – Document Management System； 21 – RFU； 22 – RFU； 23 - MPOS. | ||
| Transaction Initiation | TranInit | AN | 1 | R:Returned | 1 digit transaction initiation code : 0 – Unknown ; 1 - Attended ; 2 – Unattended ; 3 – Agent ; 4 – Batch Agent ; 5 – Delayed Authorization Unattended ; 6 – Delayed Authorization Attended. | ||
| Transaction Medium | TranMedium | AN | 1 | R:Returned | 1 digit transaction medium code : 0 – Unknown ; 1 – Magnetic Stripe Card Transaction ; 2 – Chip Card Transaction ; 3 – Magnetic Stripe Hybrid Transaction ; 4 – Virtual Card Transaction ; 5 – Manual Input Transaction ; 6 – Biological Traits Transaction ; 7 – Card Not Present Transaction. | ||
| Primary Account Number | PriAcct | AN | 8-16 | C:Conditional | 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. | ||
| Token Usage Scenario Identification | TkSubTpId | N | 2 | C:Conditional | Provided by TR Valid Values: 01: SE ; 02: HCE ; 03: QR code ; 04: Card-On-File (COF) ; 05: Digital wallet ; 06: Chip or Magstripe Card . | ||
| Token Expiry Time | TokenEnd | N | 14 | C:Conditional | Format：MMDDhhmmss. Generated according to GMT+8 time zone. The Token Expiry Date is the 3rd-6th digits of Token Expiry Time. Format: YYYYMMDDhhmmss | ||
| Product Identification | ProdId | ANS | 4 | C:Conditional | 1. Filled by TR in the Token request. The first byte indicates the product category and the last 3 bytes indicate the product sub-category. 2. Base64 encoding the entire field . | ||
| Response Code | respCd | string | 2 | M:Mandatory | |||
| Response Information | respMsg | ANS | 1-256 | M:Mandatory | Detailed information for response code. | ||
| MAC | mac | ANS | 16 | M:Mandatory |
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.
How to launch your business?
Technical Contact
Bussiness Contact
| 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 |
Kindly Reminder