By continuing your navigation on our website, you consent to the use of cookies to provide you with better services. To learn more, read our cookies policy.
x
APIs
Products & Solutions
Partner
Support
Sign in
Search
International
中国站
Open API >Security & Risk >Token Service for APP Gateway
Token Service for APP Gateway
Security & Risk Issuer
Token Service API specifies the message flows of Token transactions as well as the message requirements during processing.
Sandbox Testing
API Introduction
API Introduction
What is it?

Token Service API provide a convenient way for Issuer APP to integrate UPI token service. Issuer can apply for UnionPay tokens through this API or share tokens with partners. At the same time，Issuer can also manage token during token lifecycle，such as updating pan expiry, updating token domain restriction control or deleting token, etc.

Key Features

Token request and token lifecycle management

When to Use it?

Applicable to Issuers that want to integrate UPI token service for replacing PAN with token, or sharing token to their partners.

Who Use it?
Issuer Partners who wants to launch UPI token service
Where to Use it?
This API is available globally except for mainland China
Flow Chart
Flow Chart

  1. Token Request

TOKEN SERVICE 流程图1.png

Token Request

The app gateway can initiate TOKEN_REQUESTING transaction to UMPS system to apply for a payment token.

The app gateway can initiate TOKEN_REQUESTING transaction to UMPS system to apply for a Shared Payment Token. And apply for a Token Transaction Cryptogram via TOKEN_TRX_CRYPTOGRAM_REQUEST API.  Then APP gateway can return the Shared Payment Token and Token Transaction Cryptogram to the Token User for initiating payment transaction.

The app gateway can initiate TOKEN_REQUEST_WITH_AUTHORIZATION transaction to UMPS system to apply for a payment token with encrypted data. Please refer to Cardholder Account Management Service for more details.

2. Token Lifecycle Management

TOKEN SERVICE 流程图2.png

The application gateway can manage token information, such as Token Assurance Level, Token Expiry Date,Token State, etc.,via TOKEN_INFO_UPDATE  、TOKEN_STATE_UPDATE API；Once Token information updated, UPI will notify APP Gateway via TOKEN_INFO_UPDATE_NOTIFICATION, TOKEN_STATE_NOTIFICATION, TOKEN_CREATION_NOTIFICATION API.
API Reference
API Reference
  • TOKEN_REQUESTING
Interface description
When requesting Token from UPI, the application gateway acting as TR may initiate the Token Requesting message to the UMPS system. Then the UMPS system will forward the request message to the TSP system which will implement Token Domain Restriction Controls, generate the Token Assurance Level according to the ID&V result, and respond with a Token. The message flow is as follows.
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
Message Information msgInfo Object M:Mandatory
Version Number versionNo ANS 5 M:Mandatory Valid Values: "1.0.0" – Using SHA256+NONEWithRSA for signature; “2.0.0” – Using SHA256WithRSA for signature
Message ID msgID AN 29 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the application provider initiates on any day. The value in the response must match the value in the request. Components: “A” + Wallet ID + Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + serial code(6 numeric digits)
Time Stamp timeStamp N 14 M:Mandatory The value in the response must match the value in the request. Format: YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "TOKEN_REQUESTING"
Wallet ID walletID AN 8 M:Mandatory The unique value associated to a wallet.
Transaction Information trxInfo Object M:Mandatory
Device ID  deviceID ANS 1-64 M:Mandatory The unique value associated to a device. It shall be IMEI for Android mobile or IDFV for iOS mobile.
Primary Account Number pan AN 1-2048 C:Conditional Encrypted with the public key of the Encryption Certificate. Either “pan” or “parentToken” shall be present.
Parent Token parentToken N 16-19 C:Conditional Parent Token PAN.Filled in the scenario of Token request based on Token. Either “pan” or “parentToken” shall be present.
Cardholder Verification Information cvmInfo Object M:Mandatory Encrypted with the public key of the Encryption Certificate. List of the Cardholder Verification (CV) methods required. The mobile application shall collect this information from the Cardholder. Valid CVs: • "idType"; • "idNo"; • "name"; • "mobileNo"; • "otpValue"; • "pin" ; • "cvn2"; • "expiryDate"; Note 1: The "idType" and "idNo" shall be present together.; Note 2: If no CV method is required, the value of the object shall be "cvmInfo": {}
ID Type idType ANS 1-25 O:Optional Valid Values: "IDENTIFICATION_CARD"; "PASSPORT"
ID Number idNo AN 1-25 O:Optional
Name name S 1-30 O:Optional
Mobile Number mobileNo AN 1-25 O:Optional The Mobile Number format is defined in [ITU-T E.164]. Components: Country code (1-3 digits) + “-” + subscriber number; If the country code is not present, the UMPS system will consider it as a mobile number from Mainland China.
OTP Value otpValue ANS 1-9 O:Optional
PIN pin N 6 O:Optional
CVN2 cvn2 N 3 O:Optional
Expiry Date expiryDate AN 5 M:Mandatory Filled with the Expiry Date of parent Token in the scenario of Token request based on Token. Otherwise, filled with PAN Expiry Date. Format: MM/YY
Requested Token Expiry Time requestTokenExpiry N 12 M:Mandatory This field indicates the Requested Token Expiry Time the application gateway expects. But the Token Expiry Time will eventually be determined by the UnionPay system. Format: YYMMDDhhmmss
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 type; Terminal Type bitmap combination: ; First byte: ATM or counter ; Second byte: Mobile ; Third byte: PC ; Fourth byte: Multimedia terminal ; Fifth byte: Fixed phone terminal ; Sixth byte: POS ; Seventh byte: Others
Single Transaction Limit singleTranLmt ANS 1-13 O:Optional The maximum transaction amount of this Token for one transaction.
Accumulated Transaction Limit totalLmt ANS 1-13 O:Optional The upper limit of the accumulated transaction amount.
Accumulated Daily Transaction Limit totalDayLmt ANS 1-13 O:Optional The upper limit of the accumulated transaction amount each day.
Accumulated Monthly Transaction Limit totalMonthLmt ANS 1-13 O:Optional The upper limit of the accumulated transaction amount each month.
Limit Currency Code tranLmtCurrency N 3 O:Optional A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. When Single Transaction Limit, Accumulated Transaction Limit, Accumulated Daily Transaction Limit, or Accumulated Monthly Transaction Limit are present, they must be in the same currency.
Merchant List merchantList Array O:Optional The white list of Merchants where the Token is allowed to be used. Each Merchant can be uniquely identified by the combination of Merchant ID and Acquirer IIN. There are up to 10 Merchant IDs in the list. Format: [{"merchantID":"merchantID1”, "acquirerIIN":"acquirerIIN1"},……,{"merchantID":"merchantIDn", "acquirerIIN":"acquirerIINn"}]
Merchant ID merchantID ANS 1-15 O:Optional
Acquirer IIN acquirerIIN AN 8 O:Optional
MCC List mccList Array O:Optional List of 4-byte MCCs where this token is allowed to be used. There are up to 10 MCCs in this list.
Country Code countryCode N 3 O:Optional As defined by [ISO 3166].
Transaction Medium tranMedium AN 1 O:Optional 1-digit transaction medium allowed for this token.Valid values: 0 – Unknown; 1 – Magnetic Stripe Card Transaction; 2 – Chip Card Transaction via chip; 3 – Magstripe Transaction of Chip and Magstripe Hybrid Card; 4 – Virtual Card Transaction. 5 – QRC-based Payment Transaction; 6 – Biological Traits Transaction; 7 – Card-not-present Transaction
Maximum Use Times maxUseTimes N 3 O:Optional The upper limit of the transaction count allowed for the Token. Valid values: 001 – 999
Cardholder Identification Verification Result Bitmap valResultBit N 8 M:Mandatory Bitmap of Cardholder identification verification result. All the verification results contain a one byte verification result indicator. Valid Values: 0: indicates that the verification is not performed. 1: indicates that the verification succeeds. 2: indicates that the verification fails. Cardholder Identification Verification Result bitmap combination: First byte: ID type verification result; Second byte: ID number verification result; Third byte: Cardholder name verification result; Fourth byte: Mobile number verification result ; Fifth byte: Dynamic code verification result ; Sixth byte: PIN verification result ; Seventh byte: CVN2 verification result; Eighth byte: Expiry Date verification result
Token Location tokenStore N 2 M:Mandatory Valid Values: 01: Remote storage: An example is a card-on-file database; 02: SE storage: An example is UPI approved secure element in mobile phone/IC card ; 03: Local Device storage: An example is Payment Token data stored using the standard data storage mechanisms of a consumer controlled device; 04: Local hardware secured storage: An example is 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 Secure Element ID number. Present for mobile payment product
Token Usage Scenario Identification tkSubTpId N 2 M:Mandatory Valid Values: 01: SE ; 02: HCE; 03: QR Code ; 04: Card-On-File (COF) ; 05: Digital Wallet ; 06: Chip or Magstripe Card ; 07: Virtual Card
Shared Payment Token Indicator shareToken N 1 M:Mandatory Valid Values: 0: The Token is not allowed to be shared. 1: The Token is allowed to be shared.
Sub Token Indicator subToken N 1 M:Mandatory Valid Values: 0: Request Token based on PAN. 1: Request Token based on Token, with Token Domain Restriction Controls of parent Token or more restriction controls. 2: Request Token based on Token, without Token Domain Restriction Controls of parent Token.
Risk Information riskInfo Object O:Optional
GPS gps ANS 1-64 O:Optional Components: +(-) latitude/+(-) longitude
SIM Card simCard Array 1-200 O:Optional The mobile number of the SIM cards. The mobile phone may have more than one SIM card.
Application User ID appUserID ANS 1-64 O:Optional An alias for the application user ID.
User Enrollment Date usrEnrolDate N 6 O:Optional The date when the Cardholder registers in the wallet. Format:YYMMDD
Card Number Capture Method captureMethod ANS 1-64 O:Optional Valid Values: • "MANUAL"; • "NFC"; • "CAMERA"; • "UNKNOWN"
IP Address ipAddress ANS 1-64 O:Optional The public network IP address of the device
Reserved Mobile Number reservedMobileNo ANS 1-25 O:Optional The mobile number collected by the application when the user registered his/her account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164]; Components: Country code (1-3 digits) + “-” + subscriber number; If the country code is not present, UMPS will consider it as a mobile number from Mainland China.
Device Type deviceType ANS 1-20 O:Optional Valid Values:• “MOBILE”; Reserved Values: • “WATCH”; • “PAD”; • “PC”
Device Score deviceScore N 1 O:Optional Valid Values: “1” to “5”. “5” indicates the device is the most reliable, and “1” indicates the device is the least reliable.
Certificate and Signature certificateSignature Object M:Mandatory
Application Signature Certificate ID appSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The application gateway uses the private key of this certificate for signature.
UMPS Encryption Certificate ID umpsEncCertID AN 1-128 C:Conditional The serial number of the certificate. The application gateway uses the public key of this certificate for encryption. Present if encrypted information exists in the request message.
Signature signature ANS 1-2048 M:Mandatory Please refer to the section of Signature in UMPS Book 1 – Section 3.2 for details.
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Message Information msgInfo Object M:Mandatory
Version Number versionNo ANS 5 M:Mandatory Valid Values: "1.0.0" – Using SHA256+NONEWithRSA for signature; “2.0.0” – Using SHA256WithRSA for signature
Message ID msgID AN 29 M:Mandatory It is used to match a response to its request. The value must uniquely identify any message that the application provider initiates on any day. The value in the response must match the value in the request. Components: “A” + Wallet ID + Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + serial code(6 numeric digits)
Time Stamp timeStamp N 14 M:Mandatory The value in the response must match the value in the request. Format: YYYYMMDDhhmmss
Message Type msgType ANS 1-50 M:Mandatory Valid Value: "TOKEN_REQUESTING"
Wallet ID walletID AN 8 M:Mandatory The unique value associated to a wallet.
Transaction Information trxInfo Object M:Mandatory
Message Response msgResponse Object M:Mandatory
Response Code responseCode AN 2 M:Mandatory It contains a code that defines the response to a request. Please refer to the table of Response Code and Message in UMPS Book 1 – Table 1 for the valid values.
Response Message responseMsg S 1-100 M:Mandatory It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the Consumer of the transaction outcome.
Certificate and Signature certificateSignature Object M:Mandatory
UMPS Signature Certificate ID umpsSignCertID AN 1-128 M:Mandatory The serial number of the certificate. The UMPS system uses the private key of this certificate for signature.
Signature signature ANS 1-2048 M:Mandatory
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.
©Copyright 2002 - 2024. All rights reserved