Token

TokenInquiry

This API is used to retrieve a list of tokens associated with a given card.

Request：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Token	cardToken	Card Token	String	Maximum 19 character	Required

Response：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Record Number	recordNum	Record Number	String	Maximum 8 character	Required
2	Record List	recordList	each element is a complex element that includes the following sub-elements:
2.1	sub-elements of each element in the list	appUserId	The ID of the teller who initiated the token	String	Maximum 32 characters	Required
2.2		deviceId	The ID of the terminal which initiated the token	String	Maximum 64 characters	Required	Device ID, it shall be IMEI for Android mobile or IDFV for iOS mobile
2.3		cardMaskNumber	Card Mask Number	String	Maximum 19 characters	Required
2.4		cardToken	Card Token Number	String	Maximum 19 characters	Required
2.5		cardTokenState	Card Token State	String	Maximum 15 characters	Required	Valid values: "ACTIVE", "SUSPENDED", "DELETED"
2.6		cardTokenExpiryDate	Card Token ExpiryDate	String	YYYYMMDDHHMISS	Required	GMT+8 time zone
2.7		hceCardInfo	HCE Card Information	String	Maximum 4096 characters	Optional

TokenRequest

This API is used to request a token associated with a given card. After generating UnionPay Virtual PAN based on issuer’s mobile APP Account, this API is used to initialize Token for the Virtual PAN.

Request：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Token	cardToken	Card Token	String	Maximum 19 characters	Required
2	Card ExpiryDate	expiryDate	Card ExpiryDate	String	YYMM	Required
3	CVV2	CVV2	CVV2	String	Maximum 3 characters	Required
4	Use Case Indicator	useCaseIndicator	Use Case Indicator	Array	Maximum 100 characters	Required	Valid values: "QRC", "HCE", "SE", "COF"
5	Cardholder Verification Method	cvm	Cardholder Verification Method	Array	Maximum 225 characters	Required	Valid values: "expiryDate", "cvn2", "name", "idType", "idNo", "mobileNo", "otp". Fixed fill in ["expiryDate","cvn2"] for unee
6	HCE SDK Properties	hecSdkProperties	HCE SDK Properties	String	Maximum 4096 characters	Optional	Returned from HCE SDK.

Response：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Mask Number	cardMaskNumber	Card Mask Number	String	Maximum 19 characters	Required
2	Card Token Number	cardToken	Card Token Number	String	Maximum 19 characters	Required
3	Card Token State	cardTokenState	Card Token State	String	Maximum 15 characters	Required	Valid value: "ACTIVE"
4	Card Token ExpiryDate	cardTokenExpiryDate	Card Token ExpiryDate	String	YYYYMMDDHHMISS	Required	GMT+8 time zone
5	HCE Card Information	hceCardInfo	HCE Card Information	String	Maximum 4096 characters	Optional

TokenStateUpdate

This API is used to notify the change of the state of a given token to Coshine system. When the cardholder or the mobile application suspends, resumes, or deletes the card, the mobile application shall send the Token State Update request to change the state of the Token.

Request：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Token Number	cardToken	Card Token Number	String	Maximum 19 characters	Required
2	Card Token Action	cardTokenAction	Card Token Action	String	Maximum 15 character	Required	Valid values: "ACTIVATE", "SUSPEND", "RESUME", "DELETE"
3	Enrollment ID	enrollmentId	Enrollment ID	String	Maximum 16 characters	Optional	It is used to match the message sets within an enrollment process.

Response：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Token Number	cardToken	Card Token Number	String	Maximum 19 characters	Required
2	Card Token State	cardTokenState	Card Token State	String	Maximum 15 characters	Conditional	Valid values: "ACTIVE", "SUSPENDED", "DELETED"

TokenStateNotification

This API is used to notify the change of token status to mobile application. When the UMPS suspends, resumes, or deletes the card, the UMPS will send the Token State Notification request to notify the mobile application.

Request：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Token	cardToken	Card Token	String	Maximum 19 characters	Required
2	Card Mask Number	cardMaskNumber	Card Mask Number	String	Maximum 19 characters	Required
3	Card Token Number	cardToken	Card Token Number	String	Maximum 19 characters	Required
4	Card Token State	cardTokenState	Card Token State	String	Maximum 15 characters	Required	Valid values: "ACTIVE", "SUSPENDED", "DELETED"

Response：

TokenMetadataUpdate

This API is used to update the metadata of a token, such as token expiry date. The token metadata, e.g., token expiry date, needs to be updated from the mobile application’s side if the PAN expiry date has already been renewed.

Request：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Token Number	cardToken	Card Token Number	String	Maximum 19 character	Required
2	Card ExpiryDate	expiryDate	Card ExpiryDate	String	YYMM	Required
3	Card Token Number	cardToken	Card Token Number	String	Maximum 19 characters	Required

Response：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Token Number	cardToken	Card Token Number	String	Maximum 19 characters	Required
2	Card Token ExpiryDate	cardTokenExpiryDate	Card Token ExpiryDate	String	YYYYMMDDHHMISS	Required	GMT+8 time zone

ReplenishTokenLUK

Mobile application will call SDK API “tokenValidForProcessing” to check if there are available LUKs in SDK before payment for a given Token identified by the Token ID.

Request：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Token Number	cardToken	Card Token Number	String	Maximum 19 characters	Required
2	LUK Secret	lukSecret	LUK Secret	String	Maximum 4096 character	Required	Returned from HCE SDK.

Response：

	Data Element	Field Name	Description	Format	Length	M/O	Remark
1	Card Token Number	cardToken	Card Token Number	String	Maximum 19 characters	Required
2	Card Token Key	cardTokenKey	Card Token Key	Array	Maximum 4096 character	Required