UnionPay International Developer

Open API >Scenario Service >UPI Content & Service Platform for Channel App

UPI Content & Service Platform for Channel App

Scenario Service Acquirer Issuer Mobile Payment

The UnionPay Content & Service Platform (UCSP) establishes a common technology platform, where third party value-added services provided by merchants can be easily distributed to different channels (such as issuers' Apps).

Sandbox Testing

API Introduction

What is it?

The UnionPay Content & Service Platform (UCSP for short) establishes a common technology platform, where third party value-added services provided by merchants can be easily distributed to different channels (such as issuers’Apps). Third party value-added services as industry services, includes travel related services, parking services etc., are open source from service providers (merchants) . UCSP not only acts as an aggregated information platform, but also provides transaction interfaces for these services, connecting service providers and distributing channels. UCSP realizes two-way connection and resource integration between channels and service providers through standardized API docking.UCSP realizes two-way connection and resource integration between channels and service providers through standardized API docking.

Key Features

Abundant Contents

Channels are able to select any contents or services from the platform

Lower Costs

The costs will be much lower for the channels to introduce contents from the platform than directly from the service providers one by one

Unified Accounts

Cardholders just need to log in the App of the channels with no extra steps in the provider parts

Multiple Marketing Strategies

Multiple marketing strategies like coupon, incentive money and instant discount are supported

Convenient Payments

Support UnionPay App and other UnionPay payment methods；Provide the chances to add the payment tools of the channels

When to Use it?

When banks or tech company intend to build ecosystems by integrating various industry services into their mobile applications, therefore acting as channels

Who Use it?

Channel App, such as banks' App, UnionPay App、white label App, etc

Where to Use it?

This API is available globally except for mainland China.

Flow Chart

场景服务平台流程图.png

1. Users log in channel App

2. USCP transfer login information to Industry Partner

3. Industry Partner realize joint login;

Transaction Process:

4. Users place an order in channel App

5. Industry partner call USCP interface

6. Users pay the order and initiate transaction

7. Transaction result is returned to UCSP and Industry Partner

API Reference

CHANNEL_LOGIN_INFO
GET_CARD_LIST
GET_CARD_PAYLOAD
PAYMENT_RESULT_NOTICE

Interface description

The Channel APP submits the authorization login request CHANNEL_LOGIN_INFO to the UCSP. The UCSP returns the authorization result and the Industry Service’s URL “industryUrl” to the Channel APP if successful.

Request Method

HTTP POST

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

M:Mandatory

Format: A + 8-digit industry code + YYYYMMDDhhmmss + 6-digit random number

Channel Code

channelCode

8-12

M:Mandatory

Channel code

Channel Name

channelName

ANS

1-50

O:Optional

Client Type

clientType

O:Optional

Valid values:“0”: mobile APP;“1”: Website:“2”: Others

Industry Code

industryCode

M:Mandatory

The code is assigned by UPI when the Industry Service first connects to UCSP

User Identification

userId

ANS

1-64

M:Mandatory

The identification of user in the Channel provider

Language

language

ANS

O:Optional

The language version for the Industry Service to display, refer to ISO-639 Language Code and ISO-3166 Country Codes

Longitude

longitude

O:Optional

Latitude

latitude

O:Optional

Encrypted Data

encData

Object

C:Conditional

If the message contains sensitive information, the plaintext value of the sensitive data elements are constructed in Encrypted Data object (“encData”) in JSON format, and the whole Encrypted Data object shall be encrypted with JWE method.

Mobile Number	mobile	ANS	1-64	C:Conditional	It is required for parking industry app.
Email Address	email	ANS	1-100	O:Optional
ID Type	idType	N	1	O:Optional	Valid values:“1”: 18-digit ID card；“2”: 15-digit ID card; “3”: Military ID/ Police ID; “4”: Taiwan Resident Pass; “5”: Reserved; “6”: Other ID; “7”: Hong Kong Resident Pass; “8”: Macao Resident Pass
ID Number	idNo	ANS	18	O:Optional

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

M:Mandatory

Format: A + 8-digit industry code + YYYYMMDDhhmmss + 6-digit random number

Channel Code

channelCode

8-12

R:Returned

Channel code

Industry Code

industryCode

M:Mandatory

The code is assigned by UPI when the Industry Service first connects to UCSP

Industry URL Address

industryUrl

ANS

1-512

C:Conditional

URL of the Industry Service. Returned if successful

Message Response

msgResponse

Object

M:Mandatory

Response Code	responseCode	AN	2	M:Mandatory
Response Message	responseMsg	S	1-100	M:Mandatory
Error Details	errorDetail	S	1-255	O:Optional

Interface description

The UCSP submits the inquiry card list request to the Channel APP s for the user card list.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Note
Message ID	msgID	AN	29	M:Mandatory	Format: A + 8-digit industry code + YYYYMMDDhhmmss + 6-digit random number
Channel Code	channelCode	AN	8-12	M:Mandatory	Channel code
Industry Code	industryCode	AN	8	M:Mandatory	The code is assigned by UPI when the Industry Service first connects to UCSP
User Identification	userId	ANS	1-64	M:Mandatory	The identification of user in the Channel provider

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

M:Mandatory

Format: A + 8-digit industry code + YYYYMMDDhhmmss + 6-digit random number

Channel Code

channelCode

8-12

R:Returned

Channel code

Industry Code

industryCode

M:Mandatory

The code is assigned by UPI when the Industry Service first connects to UCSP

User Identification

userId

ANS

1-64

M:Mandatory

The identification of user in the Channel provider

Card Information

cardInfo

Array Object

M:Mandatory

Return the card list

Message Response

msgResponse

Object

M:Mandatory

Response Code	responseCode	AN	2	M:Mandatory
Response Message	responseMsg	S	1-100	M:Mandatory
Error Details	errorDetail	S	1-255	O:Optional

Interface description

The UCSP submits the get card payload request to the Channel APP s to obtain the selected card payload based on the unique card identifier.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
Message ID	msgID	AN	29	M:Mandatory	"AA123456720171230235959000031"	Format: A + 8-digit industry code + YYYYMMDDhhmmss + 6-digit random number
Channel Code	channelCode	AN	8-12	M:Mandatory	8-12 digits sequence id	Channel code
Industry Code	industryCode	AN	8	M:Mandatory	“A”+7-digits sequence id	The code is assigned by UPI when the Industry Service first connects to UCSP
User Identification	userId	ANS	1-64	M:Mandatory		The identification of user in the Channel provider
Card Identifier	cardID	AN	1-64	M:Mandatory		The card identifier is generated by the Channel app, which is unique in Channel APP

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

M:Mandatory

"AA123456720171230235959000031"

Format: A + 8-digit industry code + YYYYMMDDhhmmss + 6-digit random number

Channel Code

channelCode

8-12

R:Returned

8-12 digits sequence id

Channel code

Industry Code

industryCode

M:Mandatory

“A”+7-digits sequence id

The code is assigned by UPI when the Industry Service first connects to UCSP

User Identification

userId

ANS

1-64

M:Mandatory

The identification of user in the Channel provider

Card Identifier

cardID

1-64

M:Mandatory

The card identifier is generated by the Channel app, which is unique in Channel APP

Issuer IIN

issuerIIN

C:Conditional

Filled If Channel APP can provide

Issuer Name

issuerName

ANS

1-24

C:Conditional

Filled If Channel APP can provide

Card Type

cardType

C:Conditional

Filled If Channel APP can provide. 1=Credit Card. 2=Debit Card. 3=Prepaid Card

Encrypted Data

encData

Object

M:Mandatory

Primary Account Number	pan	N	16-19	M:Mandatory		It can be filled with the PAN or token.
PAN Expiry Date	panExpiryDate	N	4	C:Conditional		It can be filled with the PAN/token expiry date. Returned if it is present in the Channel APP. Format: YYMM
Mobile Number	mobile	ANS	1-64	O:Optional	Area code-mobile phone. Example: “86-185222892”	mobile number related to the card enroll in the card issuer

Message Response

msgResponse

Object

M:Mandatory

Response Code	responseCode	AN	2	M:Mandatory	"00"
Response Message	responseMsg	S	1-100	M:Mandatory	"Approved"
Error Details	errorDetail	S	1-255	O:Optional

Interface description

PAYMENT_RESULT_NOTICE is used by the UCSP to notify the Channel APP of payment results, including results of frontend payment and subsequent cancelation, refund transactions. If the back-end payment result notification is not confirmed and responded, the UCSP can store and forward PAYMENT_RESULT_NOTICE at interval of 2n minutes (n=0, 1, 2, 3, 4) for a maximum of 5 times. Interface provider: Channel APP

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
Message ID	msgID	AN	29	M:Mandatory	"AA123456720171230235959000031"	Format: A + 8-digit industry code + YYYYMMDDhhmmss + 6-digit random number
Channel Code	channelCode	AN	8-12	M:Mandatory	8-12 digits sequence id	Channel code
Industry Code	industryCode	AN	8	M:Mandatory	“A”+7-digits sequence id	The code is assigned by UPI when the Industry Service first connects to UCSP
User Identification	userId	ANS	1-64	M:Mandatory		The identification of user in the Channel provider
Transaction Time	txnTime	N	14	M:Mandatory		Transaction time of the payment transaction. Format: YYYYMMDDhhmmss
Currency code	currencyCode	N	3	M:Mandatory	446	Transaction currency code
Transaction Amount	txnAmt	ANS	1-13	M:Mandatory	10.1	Transaction amount
Order Id	orderId	AN	28	M:Mandatory		Order ID, generated on the merchant side
Order Description	orderDesc	ANS	1-512	O:Optional		Order description
Transaction Status	txnStatus	AN	2	M:Mandatory		Valid value: “01”: successful; “02”: failed; “03”: cancelled; “04”: refunded
Acquiring institution code	acqInsCode	AN	24	C:Conditional		Required when the access type is an acquirer
Merchant Category Code	merCatCode	N	4	C:Conditional		Required when the access type is an acquirer
Merchant Name	merName	ANS	1-40	C:Conditional		Required when the access type is an acquirer
Merchant abbreviation	merAbbr	ANS	1-16	C:Conditional		Required when the access type is an acquirer
Merchant ID	merId	AN	15	M:Mandatory
Access Type	accessType	N	1	M:Mandatory		0: Merchant direct access; 1: Acquirer access; 2: Platform merchant access

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

M:Mandatory

"AA123456720171230235959000031"

Format: A + 8-digit industry code + YYYYMMDDhhmmss + 6-digit random number

Channel Code

channelCode

8-12

R:Returned

8-12 digits sequence id

Channel code

Industry Code

industryCode

M:Mandatory

“A”+7-digits sequence id

The code is assigned by UPI when the Industry Service first connects to UCSP

User Identification

userId

ANS

1-64

M:Mandatory

The identification of user in the Channel provider

Transaction Time

txnTime

R:Returned

Transaction time of the payment transaction. Format: YYYYMMDDhhmmss

Currency code

currencyCode

R:Returned

446

Transaction currency code

Transaction Amount

txnAmt

ANS

1-13

R:Returned

10.1

Transaction amount

Order Id

orderId

R:Returned

Order ID, generated on the merchant side

Transaction Status

txnStatus

R:Returned

Valid value: “01”: successful; “02”: failed; “03”: cancelled; “04”: refunded

Acquiring institution code

acqInsCode

R:Returned

Required when the access type is an acquirer

Merchant Category Code

merCatCode

R:Returned

Required when the access type is an acquirer

Merchant Name

merName

ANS

1-40

R:Returned

Required when the access type is an acquirer

Merchant abbreviation

merAbbr

ANS

1-16

R:Returned

Required when the access type is an acquirer

Merchant ID

merId

R:Returned

Access Type

accessType

R:Returned

0: Merchant direct access; 1: Acquirer access; 2: Platform merchant access

Message Response

msgResponse

Object

M:Mandatory

Response Code	responseCode	AN	2	M:Mandatory	"00"
Response Message	responseMsg	S	1-100	M:Mandatory	"Approved"
Error Details	errorDetail	S	1-255	O:Optional

Security Requirement

UnionPay International has adopted unified security requirement, please refer to UPI Server-based API General Requirements for signature and encryption guide.

Sequence Chart

• Authorized Login Flow

Applies to the Channel APPs that provides OAUTH authorization.

Message flow:

时序图 authorized login flow.png

1.The user logins on the Channel APP client.

2.The user clicks on the Industry Service icon, requests for access to Industry Services from Channel APP. The Channel APP then sends authorized login interface CHANNEL_LOGIN_INFO to the UCSP. If the user has logged in, the Channel APP sends user information (“userId”, “mobile”/”email”, etc.) and “industryCode” to the UCSP for authorization.

3.The UCSP processes the access request, including verifying the legitimacy of the Channel, determining the access permission to the Industry Services.

4.If the authorization login is successful, UCSP returns the URL of the Industry Service. Otherwise, UCSP returns the failure notification.

5.The Channel APP receives the URL and redirects to the Industry Service page.

• Get Card Info Flow

The Channel APPs provide the card list and the payload of selected card upon requests.

Message flow:

时序图 get card info flow.png

1. The Industry Service requests the user card list in the Channel APP

1.1The Industry Service requests the UCSP for the eligible card list in the user account of Channel APP

1.2The UCSP requests the Channel APP for the card list.

1.3The Channel APP returns the masked PANs and their card identifier.

1.4The UCSP returns the masked card list to Industry Service.

2. The user selects one card for binding, payment or other business scenarios on the Industry Service page.

3. After the user selects the card, the Industry Service requests for the card payload.

3.1The Industry Service requests the UCSP for the card payload of the selected card with the card identifier.

3.2The UCSP requests the Channel APP for the card payload.

3.3The Channel APP returns the PAN/token, PAN/token expiry date and other card information.

3.4The UCSP returns the PAN/token, PAN expiry date and other card information to Industry Service.

• Frontend Payment Flow

Applies to front-end payment scenarios where the user interactions are required.

Message flow:

时序图 frontend payment flow.png

1. The user clicks on the “Submit Order” button on the Industry Service page displayed in the Channel APP. The Industry Service pushes the order information to the UCSP backend. The UCSP backend request to the downstream system to place the order. When the order is placed, it returns the UCSP cashier page URL to the Industry Service backend.

2. The Industry Service resolves the cashier page and the industry page then redirects to the cashier page.

3. If the UCSP determines that payment card information should be obtained from the Channel APP, it requests to obtain eligible card list from the Channel APP in the GET_CARD_INFO interface. After the user selects the card for payment, the UCSP obtains the card payload through GET_CARD_PAYLOAD interface. After the user confirms the payment, the acceptance result is returned to the Industry Service frontend synchronously.

4. After the UCSP receives the payment result from downstream system, the UCSP forwards the result to the Industry Service and the Channel APP in the PAYMENT_RESULT_NOTICE. If the back-end payment result notification is not confirmed and responded, the UCSP can store and forward PAYMENT_RESULT_NOTICE to the Industry Service or Channel APP at interval of 2n minutes (n=0,1,2,3,4) for a maximum of 5 times.

5. In case of network timeout where the backend of the Industry Service does not receive the payment result, the Industry Service can initiate PAYMENT_RESULT_INQUIRY to the UCSP to inquire the result.

Steps to Launch

Signing Agreement: Channels shall sign the cooperation agreement with UPI to access UCSP, including access content, fee payment and other items

System Connection: Integration development between channels and UCSP, usually it takes about 1 month, It is recommended to conduct online test after sandbox test

Business Launch: Channels will display the service icon as agreed in the APP, and UCSP will authorize the bilateral connection for them in the backend system, then user can access the service in the channel app

Marketing Campaign: Both channel and UPI can jointly promote marketing campaigns through UCSP, and coordinate marketing resources to increase user usage

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