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

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 Number	cardNumber	Card Number	String	Maximum 19 characters	Required	Masked Card Number
3	Token Reference Id	tokenRefId	Token Reference Id	String	Maximum 32 characters	Required
4	Token Requestor Id	tokenReqId	Token Requestor Id	String	Maximum 11 characters	Required
5	Scheme Token	schemeToken	Scheme Token	String	Maximum 19 characters	Required
6	Token Type	tokenType	Token Type	String	Maximum 16 characters	Required
7	Token Status	tokenStatus	Token Status	String	Maximum 11 characters	Required
8	Token Expiry Date	tokenExpiryDate	Token Expiry Date	String	Maximum 6 characters	Required
9	Token Assurance Method	tokenAssureMethod	Token Assurance Method	String	Maximum 2 characters	Required
10	Active Tokens For PAN	activeTokens	Active Tokens For PAN	Number	Maximum 4 characters	Required
11	Inactive Tokens For PAN	inactiveTokens	Inactive Tokens For PAN	Number	Maximum 4 characters	Required
12	Suspended Tokens For PAN	suspendedTokens	Suspended Tokens For PAN	Number	Maximum 4 characters	Required
13	Message Reason Code	reasonCode	Message Reason Code	String	Maximum 32 characters	Required
14	Notification Time	dateTime	Notification Time	String	Maximum 17 characters	Required
15	Client Wallet Account ID	clientWalletAccountID	Client Wallet Account ID	String	Maximum 32 characters	Conditional
16	Wallet Account Email	walletAccountEmail AddressHash	Wallet Account Email Address Hash	String	Maximum 64 characters	Conditional
17	Device ID	deviceId	Device ID	String	Maximum 48 characters	Conditional
18	Pan Source	panSource	Source of Pan	String	Enum	Required	Format: It is one of the following values: ● KEY_ENTERED ● ON_FILE ● MOBILE_BANKING_APP ● TOKEN ● CHIP_DIP ● CONTACTLESS_TAP
19	Address Verification Result	addressVerification ResultCode	Visa-defined code that describes the result of an address verification	String	Maximum 1 character	Optional	Billing Address Verification Result
20	CVV2 Result Code	cvv2ResultsCode	Card verification value 2 (CVV2) verification result	String	Enum	Optional	Format: It is one of the following values: ● M— CVV2 Match, indicates that Visa was able to verify the CVV2 value provided by the wallet provider. ● N— CVV2 No Match, indicates that Visa was not able to verify the CVV2 value provided by the wallet provider. ● P— Not processed, indicates that Visa was unable to verify the CVV2 value provided by the wallet provider. This applies for Issuers opting for CVV2 Bypass only. ● S — CVV2 should be on the card: Indicates that V.I.P. or the issuer was unable to perform CVV2 verification and notifies the merchant that the card should contain a CVV2 value. ● U — Issuer is not available, does not participate in the CVV2 Service, or participates but has not provided Visa with encryption keys: Indicates that the issuer is notparticipating in the CVV2 Service or has not provided Visa with encryption keys needed to perform verification, or that STIP has responded to an issuer-unavailable response.
21	Consumer Entry Mode	consumerEntryMode	Method of consumer entry	String	Enum	Optional	Format: It is one of the following values: ● KEY_ENTERED ● CAMERA_CAPTURED ● UNKNOWN
22	Locale	locale	Locale	String	Maximum 5 character	Optional	ISO format for language (ISO 639-1) and alpha-2 country code (ISO 3166-1 alpha-2)
23	Device Language Code	deviceLanguageCode	Device Language Code	String	Maximum 3 character	Optional	ISO 639-3 Language Code Used for retrieving Terms & Conditions
24	Device Type	deviceType	Device Type	String	Enum	Optional	Format: It is one of the following values: ● UNKNOWN ● MOBILE_PHONE, which is equivalent to value 01 in Field 125 ● TABLET, which is equivalent to value 02 in Field 125 ● WATCH ● MOBILEPHONE_OR_TABLET, which is equivalent to value 04 in Field 125 ● PC ● HOUSEHOLD_DEVICE ● WEARABLE_DEVICE ● AUTOMOBILE_DEVICE
25	Device Name	deviceName	Device Name	String	Maximum 128 characters	Optional
26	Device Number	deviceNumber	Device Number	String	Maximum 13 characters	Optional
27	OS Type	osType	Operating System Type	String	Enum	Optional	Format: It is one of the following values ● ANDROID ● IOS ● WINDOWS ● BLACKBERRY ● TIZEN ● OTHER
28	OS Version	osVersion	Operating System Version	String	Maximum 32 characters	Optional	Version of OS (e.g., 4.4.4)
29	OS Build ID	osBuildID	Operating System Build ID	String	Maximum 32 characters Optional
30	Device ID Type	deviceIDType	Device ID Type	String	Maximum 32 characters Optional
31	Device Brand	deviceBrand	Device Brand	String	Maximum 32 characters	Optional
32	Device Model	deviceModel	Device Model	String	Maximum 32 characters	Optional
33	Device Location	deviceLocation	Device Location	String	Maximum 25 characters	Optional
34	Device Index	deviceIndex	Device Index	Number	Maximum 2 characters	Conditional	Visa-assigned index of deviceID
35	Device IP Address V4	deviceIPAddressV4	Device IPv4 Address	String	Maximum 15 characters	Optional	IPv4 format(no leading zeros)
36	Location Source	locationSource	Location Source	String	Enum	Optional	Format: It is one of the following values: ● WIFI ● CELLULAR ● GPS ● OTHER
37	Token Protection Method	tokenProtectionMethod	Token Protection Method	String	Enum	Optional	SOFTWARE TRUSTED_EXECUTION_ENVIRONMENT SECURE_ELEMENT CLOUD

Response：

N/A. HTTP 200 response only.

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	Token Reference ID	tokenRefId	Secheme Token Reference Id	String	Maximum 32 characters	Conditional	If update the status of specific token
3	Token Requestor ID	tokenRequestorId	Token Requestor ID	String	Maximum 11 characters	Conditional
4	Scheme Token Action	schemeTokenAction	Card Token Action	String	Maximum 15 character	Required	Valid values: • "ACTIVATE" – not supported yet • "SUSPEND" • "RESUME" • "DELETE"
5	Description of Other Reason	reasonDesc	Description of other reason	String	Maximum 30 characters	Optional
6	Enrollment ID	enrollmentId	Enrollment ID	String	Maximum 16 characters	Optional	It is used to match the message sets within an enrollment process.

Response：

N/A. HTTP 200 response only.

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	cardToken	Card Token	String	Maximum 19 characters	Required
2	Token Reference Id	tokenReferenceID	Token Reference Id	String	Maximum 32 characters	Conditional	If update specific token
3	Token Requestor Id	tokenRequstorID	Token Requestor Id	String	Maximum 11 characters	Conditional
4	Card Issuer	cardIssuer	Card issuer name.	String	Maximum length 128 characters	Optional
5	Foreground Color	foregroundColor	Foreground color of the Digital Wallet entry for the card.	String	Maximum length 32 characters	Optional
6	Background Color	backgroundColor	Background color of the Digital Wallet UI entry.	String	Maximum length 32 characters	Optional
7	Label Color	labelColor	Label color of the Digital Wallet entry.	String	Maximum length 32 characters	Optional
8	Short Description	shortDescription	Short description of the card.	String	Maximum length 32 characters	Optional
9	Long Description	longDescription	Longer description of the card.	String	Maximum length 64 characters	Optional
9	Profile ID	profileID	Profile ID associated with the card.	String	Lowercase hex; Maximum 32	Conditional
10	Card Art	cardArtData	Card art data.	String	Array of card art reference IDs	Optional
11	Terms and Conditions ID	termsAndConditionsID	GUID filename for T&C text.	String	Maximum 64 characters	Optional
12	Privacy policy URL	privacyPolicyURL	Privacy policy URL.	String	Maximum 128 characters	Optional
13	Terms and Conditions URL	termsAndConditionsURL	T&C URL.	String	Maximum 128 characters	Optional
14	Contact	contactInfo	Contact information.	String	Contact Information structure	Optional
15	Application Info	applicationInfo	Application information.	String	Application Information structure	Optional
16	Card Art Reference ID	cardArtRefID	GUID filenames for Card Art images.	String	Array of GUID-based filenames. Maximum 32 characters	Conditional
17	Supports token notifications	supportsTokenNotifications	Supports token notifications.	Boolean	True/False	Optional
18	Supports FPAN notifications	supportsFPANNotifications	Supports FPAN notifications.	Boolean	True/False	Optional
19	Transaction history URL	transactionServiceURL	Transaction history URL.	String	Maximum 128 characters	Optional
20	Message/offer service URL	messageServiceURL	Message/offer service URL.	String	Maximum 128 characters	Optional
21	Transaction Push Topics	transactionPushTopic	Push topic for new transactions.	String	Maximum 128 characters	Conditional
22	Message Push Topics	messagePushTopic	Push topic for new messages.	String	Maximum 128 characters	Conditional
23	App Launch URL	appLaunchURL	URL passed to issuer app when launching.	String	Maximum 128 characters	Optional
24	App Launch URL Scheme	appLaunchURLScheme	URL scheme registered for deep linking.	String	Maximum 32 characters	Optional
25	Associated Store	associatedStoreIdentifiers	Mobile app store item IDs.	String	Maximum 20 characters	Optional
26	Associated Applications	associatedApplicationIdentifiers	Associated application IDs.	String	Maximum 128 characters	Optional
27	Contact Website	contactWebsite	Customer Service website.	String	Maximum 128 characters	Optional
28	Contact Email	contactEmail	Customer Service email address.	String	Maximum 32 characters	Optional
29	Contact Number	contactNumber	Customer Service phone number.	String	Maximum 32 characters	Optional
30	Contact Name	contactName	Name of issuing bank.	String	Maximum 32 characters	Required

Response：

N/A. HTTP 200 response only.

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