UnionPay International Developer

Open API >Account Service >Cardholder Account Management Service For Issuers

Cardholder Account Management Service For Issuers

Account Service Issuer 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) TR List Inquiry; (2) TOKEN_CREATION_NOTIFICATION; (3) 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 Issuers who want to integrate UPI Cardholder Account Management Service and provide account management service to their customers.

Who Use it?

Issuers 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

Linking Card
TOKEN_CREATION_NOTIFICATION
APP_LIST_INQUIRY
Persodata Download

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_CREATION_NOTIFICATION is used by UPI to inform App of token push completion notification.

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	"U0001034420171230235959000011"	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: “U”+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_STATE_NOTIFICATION"	Valid Value: "TOKEN_CREATION_NOTIFICATION"
Wallet ID	walletID	AN	8	M:Mandatory	"00010344"	The distinctive value associated to a wallet

Transaction Information

trxInfo

Object

M:Mandatory

Record ID	recordID	N		M:Mandatory
Parent Token pan	parentToken	N	16-19	M:Mandatory		Parent token pan
Token	token	N	16-19	C:Conditional		Token PAN. Presented if token type is QR/SE/COF
TokenId	tokenId	N	1-16	C:Conditional		TokenId. Presented if token type is HCE
Masked PAN	maskedPAN	ANS	16-19	M:Mandatory	"621111*********8888"	It is used to be displayed on the mobile application as the PAN, if necessary.
Token State	tokenState	ANS	1-15	M:Mandatory	"ACTIVE"	Valid values: "ACTIVE"
Token Expiry	tokenExpiry	N	12	M:Mandatory	"20201230235959"	GMT+8 time zone. Format: YYMMDDhhmmss

Certificate and Signature

certificateSignature

Object

M:Mandatory

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	"U0001034420171230235959000011"	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: “U”+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_STATE_NOTIFICATION"	Valid Value: "TOKEN_CREATION_NOTIFICATION"
Wallet ID	walletID	AN	8	M:Mandatory	"00010344"	The distinctive value associated to a wallet
Token Expiry	tokenExpiry	N	12	C:Conditional		GMT+8 time zone. Format: YYMMDDhhmmss

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. 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

Interface description

APP_LIST_INQUIRY is used to abtain the information of Token push-receiver Apps

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	"A0001034420171230235959000032"	It is used to match a response to its request. The value must uniquely identify any message that the wallet 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	" ALL_INAPP_INFO_INQUIRY "	Valid Value: "APP_LIST_INQUIRY"
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.
Key Word	keyWord	ANS	1-32	O:Optional	Key word of app name
Current page number	currentPageNo	N	1-2	C:Conditional	If app inquiries appInfo for the first time, it does not exist in request and it will be set to 1 in response. In response it exist if respCode is 00
Number of the result in each response	rowsPerPage	N	1-2	O:Optional	If not exist, default value is 10

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 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	"A0001034420171230235959000032"	It is used to match a response to its request. The value must uniquely identify any message that the wallet 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	" ALL_INAPP_INFO_INQUIRY "	Valid Value: "APP_LIST_INQUIRY"
Wallet ID	walletID	AN	8	M:Mandatory	"00010344"	The distinctive value associated to a wallet

Transaction Information

trxInfo

Object

M:Mandatory

InApp Info List	inAppInfoList	Array	1-1024	M:Mandatory	"inAppInfoList":["testApp1\|test.app.url.scheme1\|ANDROID\|00000001\|62000000001\|HCE\|test.app.url.icon1"	Format: “appName\|uri\|appOS\|walletid\|trid\|tokenSubType\|appIconUrl”. Description: appName, Mandatory; uri, Mandatory, Parameter to call app/web; appOS, Mandatory, List of appOS allowed, valid values: ANDROID, IOS, WEB; walletID, Conditional; trid, Conditional; tokenSubType, Mandatory, List of tokenSubType where token is allowed, Valid Values include: QRC, HCE, SE, COF; applconUrl, Mandatory.
Current page number	currentPageNo	N	1-2	C:Conditional		If app inquiries appInfo for the first time, it does not exist in request and it will be set to 1 in response. In response it exist if respCode is 00
Number of the result in each response	rowsPerPage	N	1-2	C:Conditional		If not exist, default value is 10
Total number of result of inApp Info	totalLength	N	1-3	C:Conditional		exist if respCode is 00
Number of total pages	totalPageNo	N	1-3	C:Conditional		exist if respCode is 00, the value is base on rowsPerPage

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

Interface description

Mobile application will call this method to do download persodata. It may be called when the application already has a QR token after finishing QR provisioning, or use pan+expiryDate, umps will generate a HCE token base on those information.

Request Method

HTTP POST

Note

The method declaration is as follows:

public void persodataDownload(

String inAppProvision,

String firebasedInstanceID,

StatusCallback<String, String> statusCallback)

Parameter 1 (String inAppProvision)

This element contains information to finish card provisioning.

Parameter 2 (String firebaseInstanceID)

Mobile application is required to get the firebase instance ID. This ID is required for MPP server to push notifications to the mobile phone via Google Firebase Notifications framework (refer to google documentation or the reference implementation on how to obtain this ID)

Parameter 3 (StatusCallback<String, String> callback)

Mobile application is to provide an object implementing the StatusCallback interface. The interface has 2 methods to be implemented.

public void success(String o)

public void failure(String o)

The first method success() will be called when the persodata download request is successful. The number of LUKs provisioned will be passed via the parameter in the success() method. If the persodata download request is not successful, the method failure() will be called passing in the error string.

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.

Card Product

Online Payment

Mobile QuickPass

QR Code

Cross-Border B2B Service

Token Program

SaaS Card Issuing Service Platform

Block Chain

Platforms

Global Service

Digital Solutions

Industry Solutions

Deferred Online ODA Mode

Real-Time Mode

Frictionless Parking

Transit QR Code Mode

Prompt

Kindly Reminder

Prompt