UnionPay International Developer

Open API >Data Service >U Collection-Premium Cardholder's Privileges

U Collection-Premium Cardholder's Privileges

Data Service Developer Merchant Issuer Mobile Payment

U Collection platform contains a series of luxury global privileges handpicked by UnionPay for Platinum and Diamond cardholders, including Dining, Shopping, Hotel, Lifestyle, Travel and other top picks. 200 top merchants covering in more than 20 countries and regions are selected to prepare experiences full of glamour. Note: This API will upgrade to a new version in 2020, new version will feature more detailed information, please stay tuned.

Sandbox Testing

API Introduction

What is it?

U Collection platform contains a series of luxury global privileges and benefits including Dining, Shopping, Hotel, Lifestyle, Travel and other top picks.

Through the API interface, users can obtain specific offer details on the U Collection platform to publish and display according to your own requirements

Key Features

High-end: Select merchants of high-end brands

Global: Cover over 20 countries and regions

High-quality: Provide attractive benefits to premium cardholders

When to Use it?

Users can use this API in following scenarios:

1. When users want to change some of the details in U Collection platform to match the structure or design of their own channels(like App, website, and so on)

2. When users want to select some of the privileges to add value to their own platforms.

Who Use it?

Issuer, Traffic entrance and Third party partners.

Where to Use it?

This API is available globally

Flow Chart

API Document

Obtain cardholder benefits (category)
Obtain cardholder benefits (country)
Obtain cardholder benefits (city)
Search cardholder benefits by criteria
Obtain cardholder benefits (detail)

Interface description

Obtain cardholders' rights classification structure.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
Access to Application Identification	appID	string	128	M-Must
Access to Application Key	appKey	string	128	M-Must
Thematic ID	thematic_id	string	96	M-Must		Privilege's theme ID
Node ID	node_id	string	96	O-Optional		Privilege's ID. If null, will return all privileges
Interface ID	procType	string	128	M-Must	queryNode

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Response Code	respCode	string	96	M-Must
Response Message	respMsg	string	96	M-Must
Thematic ID	thematic_id	string	96	M-Must
Node ID	node_id	string	96	M-Must
Node Name	node_name	string	100	M-Must
Node Grade	node_grade	int	10	M-Must
Node Type	node_type	int	10	M-Must	0：null；1：merchants and offers；2：banner；3：article。
Reserved Field	resvFld	string	300	O-Optional	Alternative field

Sample code

Request code

Other

{
 "appId": "ucollection_dining",
 "appKey": "ucollection_diningkey",
 "procType": "queryNode",
 "fields": {
  "thematic_id": "ff8080815caa4d70015cf84991180073",
  "node_id": "ff8080815caa4d70015cf84b89160076"
 }
}

Note: Request message plaintext shall be encrypted by using Key Store file in Sandbox Testing Parameters. The format of encrypted request message would be {"data":"XXXX","signature":"XXXX"}

Encrypted version of above message:
{"data":"eyJhcHBJZCI6InVjb2xsZWN0aW9uX2RpbmluZyIsInByb2NUeXBlIjoicXVlcnlOb2RlIiwiZmll\r\nbGRzIjp7InRoZW1hdGljX2lkIjoiZmY4MDgwODE1Y2FhNGQ3MDAxNWNmODQ5OTExODAwNzMiLCJu\r\nb2RlX2lkIjoiZmY4MDgwODE1Y2FhNGQ3MDAxNWNmODRiODkxNjAwNzYifSwiYXBwS2V5IjoidWNv\r\nbGxlY3Rpb25fZGluaW5na2V5In0=","signature":"LBrAC4XT2Q7sWRCSqegZ3mKdK44qj/LpJiRLMxjAlcM1jruGXKNkCCmZAfqEWkjHCMXVyFfKdq/u\r\nAq1gYer758nR2uxhTJr2/1KVKdf+4Rw8eTgaqFxNB17lAtB2aAEASpARuRnwmgQuE0uZaUA2k6i/\r\nDuPk7EFGoA6WGxnA+Iw="}

Response code

Other

{
 "respCode":"01",
 "respMsg":"success",
 "data":[{
  "node_id":"ff8080815caa4d70015cf84991180222",
  "thematic_id":"ff8080815caa4d70015cf84991180333",
  "node_name":"米其林名厨",
  "node_grade":1,
  "node_type":0,
  "resvFld":"" 
 }]
}

Interface description

Obtain the list of countries where the cardholders' privileges are.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
Access to Application Identification	appID	string	128	M-Must
Access to Application Key	appKey	string	128	M-Must
Language	lang	string		M-Must
Node ID	node_id	string	96	M-Must		Privilege's ID. If null, will return all privileges
Interface ID	procType	string	128	M-Must	queryCountry

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request
Response Code	respCode	string	96	M-Must
Response Message	respMsg	string	96	M-Must
Continent	continent	string	150	M-Must
Country ID	countryId	string	90	M-Must
Country Name	country	string	150	M-Must

Sample code

Request code

Other

{
 "appId": "ucollection_dining",
 "appKey": "ucollection_diningkey",
 "procType": "queryCountry",
 "fields": {
  "lang": "cn",
  "node_id": "ff8080815caa4d70015cf84eea49007f"
 }
}

Note: Request message plaintext shall be encrypted by using Key Store file in Sandbox Testing Parameters. The format of encrypted request message would be {"data":"XXXX","signature":"XXXX"}

Encrypted version of above message:

{"data": "eyJhcHBJZCI6InVjb2xsZWN0aW9uX2RpbmluZyIsInByb2NUeXBlIjoicXVlcnlDb3VudHJ5Iiwi\r\nZmllbGRzIjp7ImxhbmciOiJjbiIsIm5vZGVfaWQiOiJmZjgwODA4MTVjYWE0ZDcwMDE1Y2Y4NGVl\r\nYTQ5MDA3ZiJ9LCJhcHBLZXkiOiJ1Y29sbGVjdGlvbl9kaW5pbmdrZXkifQ==","signature": "AhJWcAwXdC5f+D79vWCteMf+Qet8YCA4JapkDH+lvkWBgTzivbHB651zC6O3z5Lc3KHiVt1Pe0z9\r\n/JhPabjZgKvmlVqrmwXtRWRJn4L+tZDgciEQxy/ae/H5JEhiPulX5TeWGuUZ69Hxyhm9Ya7oNz5s\r\nNNG+5MS4S9lQ0f0tBKE="

}

Response code

Other

{
 "data": [{
  "continent": "",
  "country": "阿尔巴尼亚",
  "countryId": "1005026"
 },etc

Interface description

Obtain the list of cities where the cardholders' privileges are.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
Access to Application Identification	appID	string	128	M-Must
Access to Application Key	appKey	string	128	M-Must
Language	lang	string	5	M-Must
Node ID	node_id	string	96	M-Must		Privilege's ID. If null, will return all privileges
Country ID	countryId	string	90	M-Must
Interface ID	procType	string	96	M-Must	queryCity

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request
Response Code	respCode	string	96	M-Must
Response Message	respMsg	string	96	M-Must
City ID	cityId	string	90	M-Must
City Name	city	string	150	M-Must

Sample code

Request code

Other

{
 "appId": "ucollection_dining",
 "appKey": "ucollection_diningkey",
 "procType": "queryCity",
 "fields": {
  "lang": "cn",
  "countryId": "1004035",
  "node_id": "ff8080815caa4d70015cf84eea49007f"
 }
}

Note: Request message plaintext shall be encrypted by using Key Store file in Sandbox Testing Parameters. The format of encrypted request message would be {"data":"XXXX","signature":"XXXX"}

Encrypted version of above message:

{"data":"eyJkYXRhIjpbeyJ0aGVtZW50aWNfaWQiOiJmZjgwODA4MTVjYWE0ZDcwMDE1Y2Y4NDk5MTE4MDA3\nMyIsInJlc3ZGbGQiOiIiLCJub2RlX25hbWUiOiLlnLDln5/po47lkbMiLCJub2RlX2dyYWRlIjo0\nLCJub2RlVHlwZSI6Miwibm9kZV9pZCI6ImZmODA4MDgxNWNhYTRkNzAwMTVjZjg0ZTVlYmQwMDdl\nIn0seyJ0aGVtZW50aWNfa+ZGbGQiOiIiLCJub2RlX25hbWUiOiLov57plIHlpb3lkbMiLCJub2RlX2dyYWRlIjo0LCJub2Rl\nVHlwZSI6Miwibm9kZV9pZCI6ImZmODA4MDgxNWNhYTRkNzAwMTVjZjg0ZTFhNDUwMDdkIn0seyJ0\naGVtZW50aWNfaWQiOiJmZjgwODA4MTVjYWE0ZDcwMDE1Y2Y4NDk5MTE4MDA3MyIsInJlc3ZGbGQi\nOiIiLCJub2RlX25hbWUiOiLlkI3ljqjotY/lkbMiLCJub2RlX2dyYWRlIjo0LCJub2RlVHlwZSI6\nMiwibm9kZV9pZCI6ImZmODA4MDgxNWNhYTRkNzAwMTVjZjg0ZGUyZGEwMDdjIn0seyJ0aGVtZW50\naWNfaWQiOiJmZjgwODA4MTVjYWE0ZDcwMDE1Y2Y4NDk5MTE4MDA3MyIsInJlc3ZGbGQiOiIiLCJu\nb2RlX25hbWUiOiLlhajpg6giLCJub2RlX2dyYWRlIjo0LCJub2RlVHlwZSI6Miwibm9kZV9pZCI6\nImZmODA4MDgxNWNhYTRkNzAwMTVjZjg0ZGE5MmEwMDdiIn0seyJ0aGVtZW50aWNfaWQiOiJmZjgw\nODA4MTVjYWE0ZDcwMDE1Y2Y4NDk5MTE4MDA3MyIsInJlc3ZGbGQiOiIiLCJub2RlX25hbWUiOiJi\nYW5uZXIiLCJub2RlX2dyYWRlIjo0LCJub2RlVHlwZSI6Mywibm9kZV9pZCI6ImZmODA4MDgxNWU3\nOWUxM2YwMTVlOTQyMjFiZTYwMDQyIn1dLCJyZXNwTXNnIjoic3VjY2VzcyIsInJlc3BDb2RlIjoi\nMDEifQ==","signature":"ZSXt3NqLz9XbprqtQzrF+bWNi9145hxaqVZMrrbdEGmJ7C9TtGs3TJojA01MxpYWu2OjnKPn48OMp+jzd5A2/HVhcqmuKggPnf4fp/MXFeYP83rzcZrBIDs9CLvDSsCwgHvZUNvsV9nXM/RWJUYfTxVJcIJOpimKo2BVMchv/LM="}

Response code

Other

{
 "data": [{
  "city": "休斯敦",
  "cityId": "1004035047"
 }],
 "respMsg": "success",
 "respCode": "01"
},etc

Interface description

According to the search criteria, the API can obtain the certain list of cardholders’ privileges, the search criteria including country ID and city which can be set as null.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
Access to Application Identification	appID	string	128	M-Must
Access to Application Key	appKey	string	128	M-Must
PageNumber	pageNo	int	10	M-Must
Page Size	pageSize	int	10	M-Must
Language	lang	string	5	M-Must
Country ID	countryId	string	100	O-Optional
City ID	cityId	string	100	O-Optional
Node ID	node_id	string	96	M-Must		Privilege's ID. If null, will return all privileges
Interface ID	procType	string	128	M-Must	queryPromotionList

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request
Response Code	respCode	string	96	M-Must
Response Message	respMsg	string	96	M-Must
PageNumber	pageNo	int	10	M-Must
Total Page	totalPage	int	10	M-Must
Page Size	pageSize	int	10	M-Must
ID	id	string	100	M-Must
Node ID	node_id	string	96	M-Must
Node Name	node_name	string	100	M-Must
Offer Type	offerType	string	96	M-Must
Offer ID	offerId	string	96	O-Optional
Offer Title	offerTitle	string	4000	O-Optional
Offer Image	offerImg	string	600	O-Optional
Offer Image Sort	offerImg_sort	int	10	O-Optional
Offer StartTime	offer_startTime	string		O-Optional
Offer EndTime	offer_endTime	string		O-Optional
Offer Sort	offer_sort	int	10	O-Optional
Merchant ID	merchantId	string	96	O-Optional
Merchant Name	merchantName	string	600	O-Optional
Merchant Type	merchantType	string	96	O-Optional
Country	country	string	96	O-Optional
City	city	string	96	O-Optional
wl Id	wl_id	string	96	O-Optional
wl Title	wl_title	string	1500	O-Optional
wl Sort	wl_sort	int	10	O-Optional
wl StartTime	wl_startTime	string		O-Optional
wl EndTime	wl_endTime	string		O-Optional
url wl Image	url_wlImg	string	600	O-Optional
wl Image Sort	wlImg_sort	int	10	O-Optional
wl Url	wlUrl	string	600	O-Optional
Reserved Field	resvFld	string	300	O-Optional

Sample code

Request code

Other

{
 "appId": "liuliangjigou",
 "appKey": "liuliangjigoukey",
 "procType": "queryPromotionList",
 "pageNo": "1",
 "pageSize": "5",
 "fields": {
  "lang": "cn",
  "countryId": "",
  "cityId": "",
  "node_id": "ff8080815caa4d70015cf84eea49007f"
 }
}

Note: Request message plaintext shall be encrypted by using Key Store file in Sandbox Testing Parameters. The format of encrypted request message would be {"data":"XXXX","signature":"XXXX"}

Encrypted version of above message:

{"data":"eyJhcHBJZCI6InVjb2xsZWN0aW9uX2RpbmluZyIsInBhZ2VObyI6IjEiLCJwYWdlU2l6ZSI6IjUi\r\nLCJwcm9jVHlwZSI6InF1ZXJ5UHJvbW90aW9uTGlzdCIsImZpZWxkcyI6eyJjb3VudHJ5SWQiOiIi\r\nLCJjaXR5SWQiOiIiLCJsYW5nIjoiY24iLCJub2RlX2lkIjoiZmY4MDgwODE1Y2FhNGQ3MDAxNWNm\r\nODRlZWE0OTAwN2YifSwiYXBwS2V5IjoidWNvbGxlY3Rpb25fZGluaW5na2V5In0=","signature":"B+gMG7EoWLn8aAgw6GpCjdPVyayvc/UaIB83jQBqlA10EN5v5TN3wqoMi95MOM959fnLAwXa3WdJ\r\n5ZX5IJY77Gj2q2gfDP5f3GGzgnIeWUz1PQS3wUkDuJfo/Wgv53ajpSxWkc3PxZyZ/4927kvzqZ62\r\n4Hq5JkWrFZ9/0Y5NTYM="}

Response code

Other

{
 "data": [{
  "wl_startTime": "2018-09-20 18:00:43.0",
  "country": "阿曼",
  "offer_sort": 0,
  "resvFld": "",
  "city": "达希莱地区",
  "wlUrl": "",
  "offer_endTime": "",
  "wl_sort": "0",
  "merchantName": "测试银联卡在全球商户优惠",
  "offerType": 0,
  "wl_title": "",
  "merchantId": "ff8080815caa4d70015cc950250f005f",
  "offer_startTime": "",
  "offerImg": "",
  "url_wlImg": "",
  "offerId": "ff8080815caa4d70015cc951db870060",
  "node_Name": "全部",
  "wl_id": "",
  "id": "ff8080815caa4d70015cc964ba410067",
  "wl_endTime": "2018-09-20 18:00:43.0",
  "wlImg_sort": 0,
  "merchantType": "1001",
  "node_Id": "ff8080815caa4d70015cf84eea49007f",
  "offerTitle": "测试银联卡在全球商户优惠"
 }],
 "pageNo": 1,
 "totalPage": 0,
 "respMsg": "success",
 "pageSize": 5,
 "respCode": "01"
}

Interface description

According to privilege ID to obtain the detail of the privilege.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value
Access to Application Identification	appID	string	128	M-Must
Access to Application Key	appKey	string	128	M-Must
ID	id	string	100	M-Must
Language	lang	string	5	M-Must
Interface ID	procType	string	128	M-Must	queryPromotionInfo

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request
Response Code	respCode	string	96	M-Must
Response Message	respMsg	string	96	M-Must
ID	id	string	96	M-Must
Merchant ID	merchantId	string	96	O-Optional
Merchant Name	merchantName	string	600	O-Optional
Merchant Type	merchantType	string	96	O-Optional
Address	address	string	4000	O-Optional
Longitude	longitude	int	18	O-Optional
Latitude	latitude	int	18	O-Optional
Country	country	string	100	O-Optional
City	city	string	100	O-Optional
Language	lang	string	5	O-Optional
Offer ID	offerId	string	96	O-Optional
Offer Title	offerTitle	string	4000	O-Optional
Card	card	string	4000	O-Optional
Offer StartTime	offer_startTime	string		O-Optional
Offer EndTime	offer_endTime	string		O-Optional
Offer Content	offerContent	string	4000	O-Optional
Offer Rules	offerRules	string	4000	O-Optional
Remarks	remarks	string	4000	O-Optional
Telephone	telephone	string	100	O-Optional
Reserved Field	resvFld	string	300	O-Optional

Sample code

Request code

Other

{
 "appId": "ucollection_dining",
 "appKey": "ucollection_diningkey",
 "procType": "queryPromotionInfo",
 "fields": {
  "lang": "cn",
  "id": "ff8080815ba2d6cb015bae8bd2810193"
 }
}

Note: Request message plaintext shall be encrypted by using Key Store file in Sandbox Testing Parameters. The format of encrypted request message would be {"data":"XXXX","signature":"XXXX"}

Encrypted version of above message:
{"data":"eyJhcHBJZCI6InVjb2xsZWN0aW9uX2RpbmluZyIsInByb2NUeXBlIjoicXVlcnlQcm9tb3Rpb25J\r\nbmZvIiwiZmllbGRzIjp7ImlkIjoiZmY4MDgwODE2MjA0NGVmMzAxNjIwYTAxMjdhMzAwMGQiLCJs\r\nYW5nIjoiY24ifSwiYXBwS2V5IjoidWNvbGxlY3Rpb25fZGluaW5na2V5In0=","signature":"TRXJhRQtxQBkCT2L1tvhmIEzK9N4SpRYkYTQxxS4ozKGZrALqWW/+Xro5pfMq3ZO8sqlPOf2nbbJ\r\neRS5b0fVYV4+Q0eVaG0cVHrDt438W427kCdZfLB6uaeJhYnjN9dnxtALWiSA9aepn6Rycn73tNGw\r\nHgitsVuA5ubmahUkglI="}

Response code

Other

{
 "data": [{
  "country": "中国大陆",
  "address": "",
  "offerContent": "",
  "resvFld": "",
  "city": "",
  "latitude": "",
  "offer_endTime": "2019-12-31 17:01:52.0",
  "telephone": "12312341234",
  "merchantName": "二维码商户测试2018年3月9日16:57:09",
  "merchantId": "ff80808162044ef3016209fbe40f0001",
  "offer_startTime": "2018-03-09 17:01:52.0",
  "offerRules": "<p><br><\/p><p>活动细则  \r\n<\/p><p>\r\n<\/p><p><br><\/p>",
  "offerId": "ff80808162044ef3016209ff95220009",
  "id": "ff80808162044ef301620a0127a3000d",
  "lang": "cn",
  "merchantType": "购物",
  "card": "所有银联卡（卡号以62开头）",
  "remarks": "",
  "longitude": "",
  "offerTitle": "二维码优惠测试2018年3月9日17:02:05"
 }],
 "respMsg": "success",
 "respCode": "01"
}

Response Code Reference

Response code	Description
01	success
02	sys_error
03	service_stop
04	precess_timeout
05	signature error
06	Missing necessary parameters
07	Request parameter format error
08	Request parameter type error
09	other error illegal parameter
10	Query no record

Steps to Launch

Interface Access Flow

1. The service provider releases the interface.

2. The caller applies for access.

3. The service provider approves the application and updates the interface white list.

4. The service provider generates the key pair.

6. The service provider keeps the private key and provides caller with public key and user ID (appID).

Interface Call Flow

1. The caller uses the public key to encrypt the request message, which should include caller's user identity information.

2. The service provider verifies the caller's user identity and the corresponding interface permissions.

3. The service provider decrypts the request message using the private key.

4, The service provider implements the interface function to obtain the return data.

5, The service provider uses private key to encrypt the return message.

Interface Access Flow

Interface Call Flow

Prompt

Kindly Reminder

Prompt