UnionPay International Developer

Open API >Payment >Cardholder Account Management Service For TR App

Cardholder Account Management Service For TR App

Payment Developer Merchant Acquirer Mobile Payment Internet Payment

UnionPay Cardholder Account Management Service (CAMS in short) provides a convenient way for cardholders to distribute and manage their payment credentials.

Sandbox Testing

API Introduction

What is it?

Cardholders do not need to link cards on the digital wallet or on-line (Card-On-File) merchants. Based on Token technology, under the premise of ensuring cardholders' information security, token will be pushed to these merchants and be managed direclty in Issuer App, greatly improving cardholder's payment experience. The functions mainly include: (1) Token Request; (2) Token Lifecycle Management.

Key Features

• Simplify binding card by initiating this process from issuers' App

• Avoid card information exposure and keep account confidential

• Encourage payment participation by extensive and convenient access to more third party Apps

When to Use it?

Applicable to Token Requestors who want to integrate UPI Cardholder Account Management Service and provide account management service to their customers.

Who Use it?

Acquirer, Merchant and Technical Service Provider

Where to Use it?

This API is available globally except for mainland China.

Things to Know

1. The App or website shall be provided by issuer for cardholders to initiate the token push and management.
2. Token Requestor (TR) indicates the party which stores the cardholder's token and initiates transaction with cardholder's token, such as e-wallet。
3. There are typically two types of TR, digital wallet and online merchant. The former one connects to UnionPay Mobile Payment System (UMPS), the latter one connects to UnionPay Online Payment Platform (UPOP).
4. UPI CAMS supports 3 scenarios of Issuer-TR interaction: App to App, App to Web, Web to Web. All these 3 scenarios are realized through URI method. When issuer gets the TR list from UnionPay, each TR will have 3 URI address, for iOS, Android and Web respectively. The url scheme shall be complex enough to avoid confliction with other App.
5. To ensure use experience, UnionPay recommends Issuer App to skip android/iOS scheme address first. Skip to website url happens only if the TR App is not installed on the device.
6. Sensitive information (such as Primary Account Number, PAN) is required to encrypt before transmitting it in the message.

Flow Chart

Business Procedure.png

API Document

Linking Card
TOKEN_REQUEST_WITH_AUTHORIZATION

Interface description

Linking Card interface is used to push card binding information from issuer app to third party app.

Request Method

HTTP POST

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Message Type

msgType

string

1-64

M-Must

provisionRequest

Message ID

msgID

string

1-128

M-Must

1201805140834000000

Message ID

Encrypted Data

encryptedData

string

1-2048

C-Condition

Example in plain text: {“pan”:”6250948200000004”,”expiryDate”:”12/22”}

The encrypted ciphertext of pan and expiry date which are encrypted by the encryption certificate assigned by UMPS to the Issuer. Either encryptedData or parentToken appears, and the parentToken is plaintext when it appears.

Parent Token

parentToken

string

16-19

C-Condition

Token from Issuer which will be used by TR to apply for a token. Either encryptedData or parentToken appears, and parentToken appears in plaintext when it appears.

Jump URI

jumpUri

string

1-256

M-Must

Jump URI. Provided when the APP is registered as TR to access UnionPay network (scheme or H5 address)

Issuer ID

issuerid

string

M-Must

47090344

Issuer IIN assigned by UnionPay

Card Type

cardtype

string

M-Must

Bank card account type. 1 credit card, 2 debit card

Masked Pan

maskedPan

string

M-Must

62111111****8588

Card tail number, used to show the user the card information to be bound. Format: first 8 digits+****+last 4 digits

User Name

userName

string

1-32

C-Condition

张*三, T*m, *伟

The cardholder's name (some characters are hidden), used to show the cardholder the information of card to be bound. Mandatory if the initiatorCountrycode is 156

User Phone Number

userPhoneNumber

string

1-32

C-Condition

139******11

The cardholder's mobile phone number (some numbers are hidden), used to show the cardholder the information of card to be bound. Mandatory if the initiatorCountrycode is 156

User Information Hash Value

userInfoHash

JSON Object

M-Must

User information hash value, including ID, name and mobile phone number

Hash Algorithm	hashAlgorithm	string	2	M-Must	Cross broad SHA-256, Domestic SM3	Hash algorithm. 00：SHA256, 01：SM3
User ID Hash	userIdHash	string	1-32	C-Condition	the hash of the user id	User id hash. Mandotary when the initiator is a domestic issuer（country code 156）
User Name Hash	userNameHash	string	1-32	C-Condition	the hash of the user name	User name hash. Mandatory if the initiatorCountrycode is 156
User Phone Hash	userPhoneHash	string	1-32	M-Must	the hash of the user mobile phone number	Mobile phone number hash recorded in the Issuer. Country code shall be added when hash the number and “-” shall be used between the country code and the mobile phone number. Example: China Mainland mobile phone number:137612345678, the value before hash should be: 86-13712345678; HK mobile phone number: 87654321, the value before hash should be: 852-87654321

Callback URL

callBackUrl

string

1-128

M-Must

Bank APP callback notification address, used to return the result after the TR token application succeeds

Initiator Information

initiatorInfo

JSON Object

M-Must

Initiator app information, in the doc, it refer to Issuer APP

Initiator Name	initiatorName	string	1-128	M-Must	Format: “issuer name-APP name”, two names are separated by “-”; Example: xxx bank-xxxx	Initiator app name
Initiator Country Code	initiatorCountrycode	String	3	M-Must	344 Hong Kong; 156 Mainland China	Country code of the initiator. It shall correctly indicate the country of the initiator.
Initiator Wallet ID	initiatorWalletID	string	8	C-Condition		Initiator app walletID which is assigned by UMPS. Mandatory if the initiatorCountrycode is NOT 156
Initiator TRID	initiatorTrid	string	11	C-Condition	62000001111	Initiator app TRID. Mandatary if the initiatorCountrycode is 156
Token Sub Type	tokenSubType	string	1-100	M-Must		List of tokenSubType in which the Token is allowed: "QRC"; "HCE"; SE"; "COF".
Record ID	recordID	string	1-128	M-Must		The random number generated by the initiator app, appears during card linking
Selected App Wallet ID	selectedAppWalletID	string	8	C-Condition		Third-party app WalletID
Selected TRID	selectedTrID	string	11	C-Condition		Receiver app's TRID

Selected App Information

selectedAppInfo

JSON object

M-Must

Third-party app information

Signature Information

signatureInfo

JSON object

M-Must

Third-party app signature and encrypted information

UMPS Encryption Certification ID

umpsEncCertID

string

1-128

C-Condition

The encryption certification ID assigned by umps to initiator app, must appear when encryptedInfo appears

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Default value	Note
Message Type	msgType	string	1-64	M-Must	provisionRequest	provisionRequest
Message ID	msgID	string	1-128	M-Must	1201805140834000000	Message ID
Response Code	respCode	string	2	M-Must	0	Response code
Response Message	respMsg	string	1-128	M-Must		Response information

Interface description

TOKEN_REQUEST_WITH_AUTHORIZATION is card binding interface of QR code

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	"1.0.0"	Valid Value: "1.0.0"
Message ID	msgID	AN	17-49	M-Must	"A0001034420171230235959000016"	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+serial code
Time Stamp	timeStamp	N	14	M-Must	"20170714235959"	The value in the response must match the value in the request. Format：YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M-Must	"TOKEN_REQUEST"	Valid Value: "TOKEN_REQUEST_WITH_AUTHORIZATION”
Wallet ID	walletID	AN	8	M-Must	"00010344"	The distinctive value associated to a wallet

Transaction Information

trxInfo

Object

M-Must

Device ID

deviceID

ANS

1-64

M-Must

The distinctive value associated to a device. It shall be IMEI for Android mobile, and IDFV for iOS mobile.

In-App provision

inAppProvision

ANS

1-4098

M-Must

Refer to “Technical Specification Interface between Issuer and TR” for more detail on this field, wrap the whole “Linking Card Message” under base64 format.

Use case Indicator

useCaseIndicator

Array

1-100

M-Must

[“QRC”]

List of the use cases in which the Token is allowed: Valid values includes: "QRC"; "HCE"; "SE"; "COF"

Risk Information

riskInfo

Object

O-Optional

GPS	gps	ANS	1-64	O-Optional	"+37.12/-121.23"	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	"161230"	The date when the cardholder registers in the wallet. Format: YYMMDD
Card Number Capture Method	captureMethod	ANS	1-64	O-Optional	"MANUAL"	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	“86-13900000000”	The mobile number collected by the application when the user registered his 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 Chinese mobile number.
Device Type	deviceType	ANS	1-20	O-Optional	“MOBILE”	Valid Values: “MOBILE”; Reserved Values: “WATCH”; “PAD”, “PC”
Device Score	deviceScore	N	1	O-Optional	“5”	Valid Values: “1” to “5”. “5” indicates the device is very reliable, and “1” indicates the device is less reliable.

Certificate and Signature

certificateSignature

Object

M-Must

Application Signature Certificate ID	appSignCertID	AN	1-128	M-Must	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-Condition	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-Must	Please refer to the Signature for details.

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	"1.0.0"	Valid Value: "1.0.0"
Message ID	msgID	AN	17-49	M-Must	"A0001034420171230235959000016"	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+serial code
Time Stamp	timeStamp	N	14	M-Must	"20170714235959"	The value in the response must match the value in the request. Format：YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M-Must	"TOKEN_REQUEST"	Valid Value: "TOKEN_REQUEST_WITH_AUTHORIZATION”
Wallet ID	walletID	AN	8	M-Must	"00010344"	The distinctive value associated to a wallet

Transaction Information

trxInfo

Object

M-Must

Device ID	deviceID	ANS	1-64	M-Must		The distinctive value associated to a device. It shall be IMEI for Android mobile, and IDFV for iOS mobile.
Token	token	N	16-19	C-Condition	"6200008888888888888"	Token PAN. Presented if token type is QR/SE/COF and response code is “00”
TokenId	tokenId	N	1-16	C-Condition		TokenId. Presented if token type is HCE and response code is “00”
Masked PAN	maskedPAN	ANS	16-19	C-Condition	"621111*********8888"	It is used to be displayed on the mobile application as the PAN, if necessary.
Masked Token	maskedToken	ANS	16-19	C-Condition	"620000*********8888"	It is used to be displayed on the mobile application as the device PAN, if necessary. Present if the Response Code is "00"
Token State	tokenState	ANS	1-15	C-Condition	"ACTIVE"	Valid values: "ACTIVE". Present if the Response Code is "00"
Token Expiry	tokenExpiry	N	12	C-Condition	"20201230235959"	GMT+8 time zone. Format: YYMMDDhhmmss
Token Reference ID	tokenRefID	N	16-19	C-Condition		Reference identifier for the Payment Token for which the Token Cryptogram is being requested. Optionally, a Token Reference ID may be submitted in place of the Payment Token and Token Expiry Date. Required if a Payment Token is not passed.
Cardface ID	cardfaceID	AN	1-20	C-Condition	"123"	The identifier of the card image. It can be used in the CARDFACE_DOWNLOADING message. Present if the Response Code is "00".

Message Response

msgResponse

M-Must

	Response Code	responseCode	AN	2	M-Must	"00"	It contains a code that defines the response to a request. Please refer to the Response Code and Message for the valid values.
	Response Message	responseMsg	S	1-100	M-Must	"Approved"	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 payment outcome. Please refer to the Response Code and Message for details.

Certificate and Signature

certificateSignature

Object

M-Must

Steps to Launch

Issuers and Token Requestors shall fill in the UPI Cardholder Account Management Service Application Form.

Please submit order in Support Center to contact us.

Prompt

Kindly Reminder

Prompt