UnionPay International Developer

Open API >Offers & Benefits >U Collection-Premium Cardholder's Privileges

U Collection-Premium Cardholder's Privileges

Offers & Benefits 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

数据调用类流程图.png

Access Flow:

1. API Caller apply to use APIs

2. UPI approve application, update white list and generate key pair, then provide API Caller the public key and user ID (appID)

Call Flow:

3. API Caller uses the public key to encrypt the request message which include caller’s user identity information

4. UPI verify API Caller’s identity, decrypt request message, and return response data encrypted by using private key.

API Reference

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:Mandatory
Access to Application Key	appKey	string	128	M:Mandatory
Thematic ID	thematic_id	string	96	M:Mandatory		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:Mandatory	queryNode

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request	Note
Response Code	respCode	string	96	M:Mandatory
Response Message	respMsg	string	96	M:Mandatory
Thematic ID	thematic_id	string	96	M:Mandatory
Node ID	node_id	string	96	M:Mandatory
Node Name	node_name	string	100	M:Mandatory
Node Grade	node_grade	int	10	M:Mandatory
Node Type	node_type	int	10	M:Mandatory	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:Mandatory
Access to Application Key	appKey	string	128	M:Mandatory
Language	lang	string		M:Mandatory
Node ID	node_id	string	96	M:Mandatory		Privilege's ID. If null, will return all privileges
Interface ID	procType	string	128	M:Mandatory	queryCountry

Synchronous Response parameters

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

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:Mandatory
Access to Application Key	appKey	string	128	M:Mandatory
Language	lang	string	5	M:Mandatory
Node ID	node_id	string	96	M:Mandatory		Privilege's ID. If null, will return all privileges
Country ID	countryId	string	90	M:Mandatory
Interface ID	procType	string	96	M:Mandatory	queryCity

Synchronous Response parameters

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

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:Mandatory
Access to Application Key	appKey	string	128	M:Mandatory
PageNumber	pageNo	int	10	M:Mandatory
Page Size	pageSize	int	10	M:Mandatory
Language	lang	string	5	M:Mandatory
Country ID	countryId	string	100	O:Optional
City ID	cityId	string	100	O:Optional
Node ID	node_id	string	96	M:Mandatory		Privilege's ID. If null, will return all privileges
Interface ID	procType	string	128	M:Mandatory	queryPromotionList

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request
Response Code	respCode	string	96	M:Mandatory
Response Message	respMsg	string	96	M:Mandatory
PageNumber	pageNo	int	10	M:Mandatory
Total Page	totalPage	int	10	M:Mandatory
Page Size	pageSize	int	10	M:Mandatory
ID	id	string	100	M:Mandatory
Node ID	node_id	string	96	M:Mandatory
Node Name	node_name	string	100	M:Mandatory
Offer Type	offerType	string	96	M:Mandatory
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:Mandatory
Access to Application Key	appKey	string	128	M:Mandatory
ID	id	string	100	M:Mandatory
Language	lang	string	5	M:Mandatory
Interface ID	procType	string	128	M:Mandatory	queryPromotionInfo

Synchronous Response parameters

Filed name	Identifier	Type	Length	Request
Response Code	respCode	string	96	M:Mandatory
Response Message	respMsg	string	96	M:Mandatory
ID	id	string	96	M:Mandatory
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"
}

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.

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

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

Interface Access Flow

Interface Call Flow

Interface Access Flow

Interface Call Flow

Prompt

Kindly Reminder

Prompt