UnionPay International Developer

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

Cardholder Account Management Service For TR App

Account Service 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

持卡人帐户管理流程图.png

1. Cardholder select token requestor or merchant

2. Issuer send token push provisioning to TR

3. TR send token request with authorization to UPI

4. UPI respond token

5. UPI return token creation notification to issuer

API Reference

ATM_FEEDBACK_INFORM
Linking Card
TOKEN_REQUEST_WITH_AUTHORIZATION

Interface description

The interface allows a user to provide UPI with the error details of ATM information returned by UPI.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
ATM ID	atmId	S	1-100	C:Conditional		The ATM ID that get from the result of ATM_LIST_INQUIRY and NEARBY_ATM_INQUIRY interface.
Country Code	countryCode	N	3	M:Mandatory	"156"	A 3-digit numeric value, as defined by [ISO 3166], that indicates the country code.
City Name	cityName	S	1-100	M:Mandatory		The name of the city for an ATM location.
Bank Name	bankName	S	1-100	M:Mandatory		The owner of the ATM.
Address	address	S	1-500	M:Mandatory		The address of an ATM
Longitude	longitude	S	1-100	O:Optional	“+30”	Longitude of the ATM's location.
Latitude	latitude	S	1-100	O:Optional	“-120”	Latitude of the ATM's location.
Report Reason	reportReason	N	1	M:Mandatory	"0"	This provides the error of ATM information, including the following values:“0”: "There is no ATM at this address"“1”: "The ATM belongs to the wrong bank or city"“2”: "The address description of ATM is not accurate"“3”: "The ATM belongs to the wrong bank or city"“4”: "ChipCard not supported"“5”: “There is a new ATM at this address”“6”: “Others”
Other Reason	otherReason	S	1-100	O:Optional	0	This provides other error of ATM information.

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message Response

　msgResponse

Object

M:Mandatory

Response Code	responseCode	AN	2	M:Mandatory	"00"	It contains a code that defines the response to a request.
Response Message	responseMsg	S	1-100	M:Mandatory	"Approved"	It contains the request result and the rejection reason if the request fails. The value of this field can be displayed by the Gateway to notify the user of the request outcome.
Error Details	errorDetail	S	1-255	O:Optional	“The Issuer response is time out.”	It contains additional detail regarding the problem identified in the message. The information is only for debug purpose. It shall not be displayed to the user.

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:Mandatory

provisionRequest

Message ID

msgID

string

1-128

M:Mandatory

1201805140834000000

Message ID

Encrypted Data

encryptedData

string

1-2048

C:Conditional

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:Conditional

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:Mandatory

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

Issuer ID

issuerid

string

M:Mandatory

47090344

Issuer IIN assigned by UnionPay

Card Type

cardtype

string

M:Mandatory

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

Masked Pan

maskedPan

string

M:Mandatory

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:Conditional

张*三, 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:Conditional

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:Mandatory

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

Hash Algorithm	hashAlgorithm	string	2	M:Mandatory	Cross broad SHA-256, Domestic SM3	Hash algorithm. 00：SHA256, 01：SM3
User ID Hash	userIdHash	string	1-32	C:Conditional	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:Conditional	the hash of the user name	User name hash. Mandatory if the initiatorCountrycode is 156
User Phone Hash	userPhoneHash	string	1-32	M:Mandatory	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:Mandatory

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

Initiator Information

initiatorInfo

JSON Object

M:Mandatory

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

Initiator Name	initiatorName	string	1-128	M:Mandatory	Format: “issuer name-APP name”, two names are separated by “-”; Example: xxx bank-xxxx	Initiator app name
Initiator Country Code	initiatorCountrycode	String	3	M:Mandatory	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:Conditional		Initiator app walletID which is assigned by UMPS. Mandatory if the initiatorCountrycode is NOT 156
Initiator TRID	initiatorTrid	string	11	C:Conditional	62000001111	Initiator app TRID. Mandatary if the initiatorCountrycode is 156
Token Sub Type	tokenSubType	string	1-100	M:Mandatory		List of tokenSubType in which the Token is allowed: "QRC"; "HCE"; SE"; "COF".
Record ID	recordID	string	1-128	M:Mandatory		The random number generated by the initiator app, appears during card linking
Selected App Wallet ID	selectedAppWalletID	string	8	C:Conditional		Third-party app WalletID
Selected TRID	selectedTrID	string	11	C:Conditional		Receiver app's TRID

Selected App Information

selectedAppInfo

JSON object

M:Mandatory

Third-party app information

Signature Information

signatureInfo

JSON object

M:Mandatory

Third-party app signature and encrypted information

UMPS Encryption Certification ID

umpsEncCertID

string

1-128

C:Conditional

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:Mandatory	provisionRequest	provisionRequest
Message ID	msgID	string	1-128	M:Mandatory	1201805140834000000	Message ID
Response Code	respCode	string	2	M:Mandatory	0	Response code
Response Message	respMsg	string	1-128	M:Mandatory		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:Mandatory

Version Number	versionNo	ANS	5	M:Mandatory	"1.0.0"	Valid Value: "1.0.0"
Message ID	msgID	AN	17-49	M:Mandatory	"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:Mandatory	"20170714235959"	The value in the response must match the value in the request. Format：YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	"TOKEN_REQUEST"	Valid Value: "TOKEN_REQUEST_WITH_AUTHORIZATION”
Wallet ID	walletID	AN	8	M:Mandatory	"00010344"	The distinctive value associated to a wallet

Transaction Information

trxInfo

Object

M:Mandatory

Device ID

deviceID

ANS

1-64

M:Mandatory

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:Mandatory

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:Mandatory

[“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: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 Signature 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	"1.0.0"	Valid Value: "1.0.0"
Message ID	msgID	AN	17-49	M:Mandatory	"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:Mandatory	"20170714235959"	The value in the response must match the value in the request. Format：YYYYMMDDhhmmss
Message Type	msgType	ANS	1-50	M:Mandatory	"TOKEN_REQUEST"	Valid Value: "TOKEN_REQUEST_WITH_AUTHORIZATION”
Wallet ID	walletID	AN	8	M:Mandatory	"00010344"	The distinctive value associated to a wallet

Transaction Information

trxInfo

Object

M:Mandatory

Device ID	deviceID	ANS	1-64	M:Mandatory		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:Conditional	"6200008888888888888"	Token PAN. Presented if token type is QR/SE/COF and response code is “00”
TokenId	tokenId	N	1-16	C:Conditional		TokenId. Presented if token type is HCE and response code is “00”
Masked PAN	maskedPAN	ANS	16-19	C:Conditional	"621111*********8888"	It is used to be displayed on the mobile application as the PAN, if necessary.
Masked Token	maskedToken	ANS	16-19	C:Conditional	"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:Conditional	"ACTIVE"	Valid values: "ACTIVE". Present if the Response Code is "00"
Token Expiry	tokenExpiry	N	12	C:Conditional	"20201230235959"	GMT+8 time zone. Format: YYMMDDhhmmss
Token Reference ID	tokenRefID	N	16-19	C:Conditional		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:Conditional	"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:Mandatory

	Response Code	responseCode	AN	2	M:Mandatory	"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:Mandatory	"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:Mandatory

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