UnionPay International Developer

Open API >Primary Credit Transaction >Remittance & P2P Transfer

Remittance & P2P Transfer

Primary Credit Transaction Acquirer

Remittance & P2P Transfer interface intend to better assist UPI Members outside of Mainland China in implementing primary credit business, including cross-border remittance (MoneyExpress) and domestic P2P transfer,etc.

Sandbox Testing

API Introduction

What is it?

Remittance & P2P Transfer interface intend to better assist UPI Members outside of Mainland China in implementing primary credit business, including but not limited to cross-border remittance and domestic P2P transfer, push purchase and push cash withdrawal, etc., making it easier for UPI members to extend business scope.

Key Features

1. Lower technology threshold and reduce development cost for institutions to luanch business.

2. API other than previous ISO format make it easier for institutions to access.

3. Applies to multiple scenarios, including cross-border remittance, domestic P2P, etc.

4. JWS, JWE are used to sign and encrypt online messagesto ensure security. Sensitive data will be encrypted before stored.

When to Use it?

The business scenarios including cross-border remittance and domestic P2P transfer.

Who Use it?

UPI Members who participate in the primary credit business and software developers.

Where to Use it?

This API is available globally except for Mainland China.

Things to Know

Sending Party (SP in short)refers to:

•Sending Institution in Money Express

•Sending Organization in P2P transfer

•Payer’s Account Management Institution in Push Purchase and Push Cash Withdrawal

•Acquiring Organization in Cash Rebate, B2B Payout, and Tax Refund

Receiving Party (RP) refers to:

•Receiving Institution in Money Express

•Receiving Organization in P2P transfer

•Payee’s Account Management Institution in Push Purchase and Push Cash Withdrawal,

•Issuing Organization in Cash Rebate, B2B Payout, and Tax Refund.

Flow Chart

汇款流程图.png

API Reference

CREDIT VERIFY
PRIMARY CREDIT
PUSH PRIMARY CREDIT
MESSAGE RESULT INQUIRY
EXCHANGE RATE INQUIRY
PUSH PURCHASE REFUND

Interface description

For cross-border remittance and domestic P2P transfer, the Sending Party initiates CREDIT_VERIFY request to UPI API to confirm the payee’s account validity before sending out the PRIMARY_CREDIT request.

Request Method

HTTP POST

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

M:Mandatory

"S00010340001034420171230235959000000"

It is used to match a response to its request. The value must uniquely identify any message that the institution initiates on any day. Format: “S”+ Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits) Transmission Date and Time shall be filled by Beijing time (UTC+8).

Sending Party IIN

sendPartyIIN

M:Mandatory

"00020344"

The distinctive value associated to the Sending Party which manages Payer’s account.

Forwarding IIN

forwardingIIN

M:Mandatory

“00010344”

The distinctive value associated to the institution that connected to UPI.

Local Transaction Date &Time

localTxnDateTime

M:Mandatory

Format: MMDDhhmmss

Card Information Capture Method

captureMethod

M:Mandatory

"94"

Valid Values: “01”: Manual; “02”: Magnetic stripe read; "03": Consumer-presented QR Code (QRC), chip information included; "04": Consumer-presented QRC (barcode), chip information excluded; "05": Integrated circuit card read, card data reliable (contact); "07": qUICS Debit/Credit Integrated Circuit Card read (contactless); “10”: Stored Credential; “93”: Merchant-presented QRC, chip information included; “94”: Merchant-presented QRC (barcode), chip information excluded; Other values: Reserved

Merchant ID

merchantID

ANS

1-15

M:Mandatory

The merchant identifier associated to a merchant of the acquirer.

Merchant Category Code

mcc

M:Mandatory

"6012"

A 4-digit numeric value, as defined by [UPI OR], indicates the merchant type.

Merchant Country Code

merchantCountry

M:Mandatory

“156”

A 3-digit numeric value, as defined in Technical Specifications on Bankcard Interoperability – Part VI Annex, indicates the country code of the merchant.

Merchant Name

merchantName

ANS

1-25

M:Mandatory

"UnionPay International"

Merchant City

merchantCity

ANS

1-12

M:Mandatory

"Shanghai"

Terminal ID

terminalID

ANS

1-8

M:Mandatory

The unique value associated to the terminal.

Staged Digital Wallet (SDW) ID

sdwID

C:Conditional

"00010344"

For definition and business cope of SDW, please refer to [UPI OR]. It is present if SDW is used to initiate the transaction.

Device ID

deviceID

ANS

1-40

C:Conditional

The distinctive value associated to a device. It shall be IMEI for Android mobile, and IDFV for iOS mobile. It is present if mobile device is used to initiate the transaction.

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

"101.10"

The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. When the amount includes decimals, the "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The following are examples of valid Transaction Amounts: "98.73", "98" and "98.". The following are NOT valid Transaction Amounts: "98,73" and "3 705".

Transaction Currency

trxCurrency

M:Mandatory

A 3-digit numeric value, in line with ISO 4217, indicates the currency code of the transaction. The mobile application can display the transaction currency in a readable way, such as "RMB".

Fund Source

fundSource

M:Mandatory

“3”

Valid values：0 – cash ; 1 – debit card; 2 – credit card; 3 – account funds

Encrypted Data

encData

Object

M:Mandatory

Payer’s Name	payerName	ANS	1-30	M:Mandatory	“Zhang San”	Chinese spelling letters (PIN YIN) are used if Chinese names are submitted.
Payer’s Account	payerAccount	ANS	1-19	C:Conditional	"6200008888888888888"	It can be filled with payer's PAN or token or account number. It is present if und source is not cash.
Payee’s PAN	payeePan	N	13-19	M:Mandatory	"6200008888888888888"	It can be filled with payee's PAN or token.
Payee’s Name	payeeName	ANS	1-30	C:Conditional	“Li Si”	Chinese spelling letters (PIN YIN) are used if Chinese names are submitted. It is present if required by local regulations.
Payer’s ID Type	payerIdType	N	2	O:Optional	“01”	Valid Values: “01”: ID card; “03”: Passport
Payer’s ID Number	payerIdNo	ANS	1-20	O:Optional	"12345678"

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

R:Returned

"S00010340001034420171230235959000000"

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

"101.10"

Transaction Currency

trxCurrency

R:Returned

A 3-digit numeric value, in line with ISO 4217, indicates the currency code of the transaction. The mobile application can display the transaction currency in a readable way, such as "RMB".

Business Indication

businessIndication

C:Conditional

“A1”

Valid value: “A1”: Inbound China Remittance; “07”: Cross-border Remittance Outside of Mainland China. “08” Domestic P2P Outside of Mainland China; It is present if successful.

Receiving Party Name

receivePartyName

ANS

1-60

C:Conditional

“ABCD Bank”

The name of the Receiving Party which manages Payee’s account. It is present if successful.

Message Response

msgResponse

Object

M:Mandatory

Response Code	responseCode	AN	2	M:Mandatory	"00"	It contains a code that defines the response to a request.
Response Message	responseMsg	S	1-100	M:Mandatory	"Approved"	It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the payer of the payment outcome.
Error Detail	errorDetail	S	1-255	O:Optional	“The Issuer response is time out.”	It contains additional detail regarding the problem identified in the message. The information is only for debug purpose. It shall not be displayed to the customer, cashier, etc.

Interface description

For cross-border remittance, domestic P2P transfer, etc., the Sending Party initiates PRIMARY_CREDIT request to UPI API to transfer fund into payee’s account.

Request Method

HTTP POST

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

M:Mandatory

"S00010340001034420171230235959000000"

Original Message ID

originalMsgID

C:Conditional

“S0001034420190711235959123456”

The same value as the “msgID” of the corresponding CREDIT VERIFY message. It shall be present in cross-border remittance and domestic P2P business (the value of "businessIndication" is "07", "08" or "A1").

Forwarding IIN

forwardingIIN

M:Mandatory

“00010344”

The distinctive value associated to the institution that connected to UPI.

Sending Party IIN

sendPartyIIN

M:Mandatory

"00020344"

The distinctive value associated to the Sending Party which manages Payer’s account.

Local Transaction Date &Time

localTxnDateTime

M:Mandatory

Format: MMDDhhmmss

Card Information Capture Method

captureMethod

M:Mandatory

Valid Values: “01”: Manual; “02”: Magnetic stripe read; "03": Consumer-presented QR Code, chip information included; "04": Consumer-presented QRC (barcode also), chip information excluded; "05": Integrated circuit card read, card data reliable (contact); "07": UICS Debit/Credit Integrated Circuit Card read (contactless); “10”: Stored Credential; “93”: Merchant-presented QRC, chip information included; “94”: Merchant-presented QRC (barcode also), chip information excluded; Other values: Reserved

Terminal Type

terminalType

M:Mandatory

“08”

Valid Values: 03: POS; 06: Counter; 07: PC; 08: Mobile Device;"24": PAD; "25": Watch Other values: Reserved

Merchant ID

merchantID

ANS

1-15

M:Mandatory

The merchant identifier associated to a merchant of the acquirer.

Merchant Category Code

mcc

M:Mandatory

"6012"

A 4-digit numeric value indicates the merchant type.

Merchant Country Code

merchantCountry

M:Mandatory

“156”

A 3-digit numeric value indicates the country code of the merchant.

Merchant Name

merchantName

ANS

1-25

M:Mandatory

"UnionPay International"

In Push Purchase and Push Cash Withdrawal transaction (the value of "businessIndication" is "21" or "22"), when the Merchant name is not available by the Payer, it shall be filled with “merchant payment” by default in the request message and the Payee shall respond with the genuine merchant name, which will be included in the settlement file.

Merchant City

merchantCity

ANS

1-12

C:Conditional

"Shanghai"

In Push Purchase and Push Cash Withdrawal transaction (the value of "businessIndication" is "21" or "22"), when the Merchant City is not available by the Payer, it could be absent in the request message and the Payee shall respond with the genuine merchant city, which will be included in the settlement file.

Terminal ID

terminalID

ANS

1-8

C:Conditional

The unique value associated to the terminal. It is present in POS or counter transactions (“terminalType” = “03” or “06”).

Staged Digital Wallet (SDW) ID

sdwID

C:Conditional

"00010344"

It is present if SDW is used to initiate the transaction.

Payment Facilitator ID (PF ID)

“pfID”

C:Conditional

The Payment Facilitator ID assigned by UPI. It is present if the transaction is submitted by Merchants registered with the Payment Facilitator, who contracts with the Sending Party as TPSP.

Device ID

deviceID

ANS

1-64

C:Conditional

The distinctive value associated to a device. It shall be IMEI for Android mobile, and IDFV for iOS mobile. It is present if mobile device is used to initiate the transaction.

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

"101.10"

The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as decimal mark. When amount includes decimals, "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The value must include the transaction fee amount if it exists.

Transaction Fee Amount

trxFeeAmt

ANS

1-13

C:Conditional

"1.10"

The tip or the convenience fee. It is present if the Tip or Convenience Fee exists.

Fund Source

fundSource

M:Mandatory

Valid values：0 – cash; 1 – debit card; 2 – credit card; 3 – account funds

Business Indication

businessIndication

M:Mandatory

“A1”

Valid value: “07”: Cross-border Remittance Outside of Mainland China; “08” Domestic P2P Outside of Mainland China; “21”: Push Cash Withdrawal; “22”: Push Purchase; “A1”: Inbound China Remittance

Encrypted Data

encData

Object

M:Mandatory

Payer’s Name	payerName	ANS	1-30	M:Mandatory	“Zhang San”	Chinese spelling letters (PIN YIN) are used if Chinese names are submitted.
Payer’s Account	payerAccount	ANS	1-19	C:Conditional	"6200008888888888888"	It can be filled with payer's PAN or token or account number. It is present if und source is not cash.
Payee’s Pan	payeePan	ANS	13-19	M:Mandatory	"6200008888888888888"	It can be filled with payee's PAN or token.
Payee’s Name	payeeName	ANS	1-30	C:Conditional	“Li Si”	Chinese spelling letters (PIN YIN) are used if Chinese names are submitted. It is present if required by local regulations.
Payer’s ID Type	payerIdType	N	2	O:Optional	“01”	Valid Values: “01”: ID card; “03”: Passport
Payer’s ID Number	payerIdNo	ANS	1-20	O:Optional	"12345678"

Payer’s Information

payerInfo

Object

C:Conditional

This Payer’s Information is in use of verification or anti money laundering. It is present upon business requirement.

Payer’s Birthday	payerBirthday	N	8	C:Conditional	Format: YYYYMMDD. It is present upon business requirement.
Payer’s Gender	payerGender	ANS	1	C:Conditional	Valid values: M: Male; F: Female; O: Others.; It is present upon business requirement.
Payer’s Nationality	payerNationality	ANS	3	C:Conditional	The country code of nationality. It is present upon business requirement.
The Country of Payer’s Permanent Residence	permanentCountry	ANS	3	C:Conditional	The country code of the permanent residence.It is present upon business requirement.
The City of Payer’s Permanent Residence	permanentCity	ANS	40	C:Conditional	It is present upon business requirement.
The address of Payer’s permanent residence	permanentAddress	ANS	80	C:Conditional	It is present upon business requirement.
Indicator of Whether the Payer and Payee is the Same Person	isSamePerson	N	1	C:Conditional	This subfield indicates whether the payer and payee is the same person. It shall be filled by payer. Valid values: 0 – The payer and payee is not the same person; 1 – The payer and payee is the same person; It is present upon business requirement.
Additional Data Required by Regulator	additionalData	ANS	50	C:Conditional	In cross-border remittance or domestic P2P (the value of "businessIndication" is "07", "08" or "A1"), this field shall be filled as required by local regulator if information above cannot be filled.
Note	note	ANS	50	C:Conditional	The note transmits the message that the payer passes to the payee. This tag shall follow rules: a. UTF-8 encoded.;b. For P2P transaction, this tag will be filled in the local language.; Payee can display the note in bill for the cardholder.; It is present upon business requirement.

Risk Information

riskInfo

Object

O:Optional

GPS	gps	ANS	1-64	O:Optional	"+37.12/-121.23"	Components: +(-) latitude/+(-) longitude
SIM Card	simCard	Array	1-200	O:Optional		The mobile number of the SIM cards. The mobile phone may have more than one SIM card.
Application User ID	appUserID	ANS	1-64	O:Optional		An alias for the application user ID
User Enrollment Date	usrEnrolDate	N	6	O:Optional	"161230"	The date when the cardholder registers in the wallet. Format: YYMMDD
IP Address	ipAddress	ANS	1-64	O:Optional		The public network IP address of the device
Reserved Mobile Number	reservedMobileNo	ANS	1-25	O:Optional	“86-13900000000”	The mobile number collected by the application when the user registered his account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164] . Components:Country code (1-3 digits) + “-” + subscriber number If the country code is not present, UPI API will consider it as a Chinese mobile number.
Device Score	deviceScore	N	1	O:Optional	“5”	Valid Values: “1” to “5”. “5” indicates the device is very reliable, and “1” indicates the device is less reliable.

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

R:Returned

"S00010340001034420171230235959000000"

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

"101.10"

Receiving Party IIN

“receivePartyIIN”

C:Conditional

The distinctive value associated to the Receiving Party which manages Payee’s account. It is present if the transaction is successful.

Settlement Key

"settlementKey"

C:Conditional

Used to match a corresponding transaction record in the settlement file. When exceptional processing occurs, the transaction may be settled using a different key set. This field is returned if "settlementKey" is different from the settlement key in “msgID”. When "settlementKey" is returned, the Member shall use "settlementKey" instead for reconciliation. Format: Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits)

Settlement Date

settlmtDate

C:Conditional

Format: MMDD It is present if the transaction is successful.

Settlement Amount

settlmtAmt

ANS

1-13

C:Conditional

It is present when transaction currency is different from settlement currency and the transaction is successful.

Settlement Currency

settlmtCurrency

C:Conditional

It is present when transaction currency is different from settlement currency and the transaction is successful.

Settlement Conversion Rate

settlmtConvRate

C:Conditional

It is present when transaction currency is different from settlement currency and the transaction is successful.

Cardholder Billing Amount

billingAmt

ANS

1-13

C:Conditional

It is present when transaction currency is different from cardholder billing currency and the transaction is successful.

Cardholder Billing Currency

billingCurrency

C:Conditional

It is present when transaction currency is different from cardholder billing currency and the transaction is successful.

Cardholder Billing Conversion Rate

billingConvRate

C:Conditional

It is present when transaction currency is different from cardholder billing currency and the transaction is successful.

Retrieval Reference Number

retrievalReferenceNumber

C:Conditional

It is present if successful.

Payment Reference Number (PAR)

par

C:Conditional

It is present when PAR is available.

Message Response

msgResponse

Object

None

Response Code	responseCode	AN	2	M:Mandatory	"00"	It contains a code that defines the response to a request.
Response Message	responseMsg	S	1-100	M:Mandatory	"Approved"	It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the payer of the payment outcome.
Error Detail	errorDetail	S	1-255	O:Optional	“The Issuer response is time out.”	It contains additional detail regarding the problem identified in the message. The information is only for debug purpose. It shall not be displayed to the customer, cashier, etc.

Interface description

For push purchase and push cash withdrawal, the Sending Party initiates PUSH_PRIMARY_CREDIT request to UPI API to transfer fund into payee’s account.

Request Method

HTTP POST

Request Parameter

Field name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

M:Mandatory

"S00010340001034420171230235959000000"

It is used to match a response to its request. The value must uniquely identify any message that the institution initiates on any day. Format: “S”+ Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits).Transmission Date and Time shall be filled by Beijing time (UTC+8).

Forwarding IIN

forwardingIIN

M:Mandatory

“00010344”

The distinctive value associated to the institution that connected to UPI.

Sending Party IIN

sendPartyIIN

M:Mandatory

"00020344"

The distinctive value associated to the Sending Party which manages Payer’s account.

Local Transaction Date &Time

localTxnDateTime

M:Mandatory

Format: MMDDhhmmss

Card Information Capture Method

captureMethod

M:Mandatory

"94"

Valid Values: “01”: Manual; “94”: Merchant-presented QRC (barcode also), chip information excluded; Other values: Reserved; For manual input and NFC payment, filled with “01” in the request message.

Terminal Type

terminalType

M:Mandatory

“08”

Valid Values: “08”: Mobile Device; Other values: Reserved

Merchant Category Code

mcc

C:Conditional

"6012"

Filled with the genuine mcc in the request message unless the mcc cannot be obtained. In this case, it is filled with “6012” by default. The genuine MCC shall be returned, which will be included in the settlement file. Only “6052” or “6010” shall be filled in push cash withdrawal.

Merchant Country Code

merchantCountry

C:Conditional

“156”

The genuine merchant country code shall be returned, which will be included in the settlement file.

Merchant Name

merchantName

ANS

1-25

C:Conditional

"UnionPay International"

Filled with the genuine merchant name in the request message unless the merchant name cannot be obtained. In this case, this field is not submitted. The genuine merchant name shall be returned, which will be included in the settlement file.

Merchant City

merchantCity

ANS

1-12

C:Conditional

"Shanghai"

Filled with the genuine merchant city in the request message unless the merchant city cannot be obtained from merchant-presented QR. In this case, this field is not submitted. The genuine merchant city shall be returned, which will be included in the settlement file.

Device ID

deviceID

ANS

1-40

C:Conditional

The distinctive value associated to a device. It shall be IMEI for Android mobile, and IDFV for iOS mobile. It is present if mobile device is used to initiate the transaction.

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

"101.10"

Transaction Currency

trxCurrency

M:Mandatory

"156"

A 3-digit numeric value, in line with ISO 4217, indicates the currency code of the transaction. The mobile application can display the transaction currency in a readable way, such as "RMB". The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist.

Transaction Fee Amount

trxFeeAmt

ANS

1-13

C:Conditional

"1.10"

The tip or the convenience fee. It is present if the Tip or Convenience Fee exists.

Fund Source

fundSource

M:Mandatory

Valid values：0 – cash; 1 – debit card; 2 – credit card; 3 – account funds

Merchant-presented QR Code Payload

mpqrcPayload

1-512

C:Conditional

It contains the raw payload data in the merchant-presented QR code. It is present if it is a Merchant presented QRC transaction.

Business Indication

businessIndication

M:Mandatory

“21”

Valid value: "21": Push Cash Withdrawal; "22": Push Purchase

Encrypted Data

encData

Object

M:Mandatory

Payer’s Name	payerName	ANS	1-30	C:Conditional	“Zhang San”	Chinese spelling letters (PIN YIN) are used if Chinese names are submitted. It shall be present in push cash withdrawal.
Payer’s Account	payerAccount	ANS	1-19	M:Mandatory	"6200008888888888888"	It can be filled with payer's PAN or token or account number.
Payee’s PAN	payeePan	N	13-19	M:Mandatory	"6200008888888888888"	It can be filled with payee's PAN or token.
Payee’s Name	payeeName	ANS	1-30	C:Conditional	“Li Si”	Chinese spelling letters (PIN YIN) are used if Chinese names are submitted. It is present if required by local regulations.
Payer’s ID Type	payerIdType	N	2	O:Optional	“01”	Valid Values:• “01”: ID card; • “03”: Passport
Payer’s ID Number	payerIdNo	ANS	1-20	O:Optional	"12345678"

Payer’s Information

payerInfo

Object

C:Conditional

This Payer’s Information is in use of verification or anti money laundering. It is present upon business requirement.

Payer’s Birthday	payerBirthday	N	8	C:Conditional	YYYYMMDD; It is present upon business requirement.
Payer’s Gender	payerGender	ANS	1	C:Conditional	Valid values: M: Male; F: Female; O: Others; It is present upon business requirement.
Payer’s Nationality	payerNationality	ANS	3	C:Conditional	The country code of nationality.It is present upon business requirement.
The Country of Payer’s Permanent Residence	permanentCountry	ANS	3	C:Conditional	The country code of the permanent residence.It is present upon business requirement.
The City of Payer’s Permanent Residence	permanentCity	ANS	1-40	C:Conditional	It is present upon business requirement.
The address of Payer’s permanent residence	permanentAddress	ANS	1-80	C:Conditional	It is present upon business requirement.
Indicator of Whether the Payer and Payee is the Same Person	isSamePerson	N	1	C:Conditional	This subfield indicates whether the payer and payee is the same person. It shall be filled by payer. Valid values: 0 – The payer and payee is not the same person. 1 – The payer and payee is the same person; It is present upon business requirement.
Additional Data Required by Regulator	additionalData	ANS	1-50	C:Conditional	In cross-border remittance or domestic P2P (the value of "businessIndication" is "07", "08" or "A1"), this field shall be filled as required by local regulator if information above cannot be filled.
Note	note	ANS	1-50	C:Conditional	The note transmits the message that the payer passes to the payee. This tag shall follow rules: a. UTF-8 encoded; b. For P2P transaction, this tag will be filled in the local language; Payee can display the note in bill for the cardholder; It is present upon business requirement.

Risk Information

riskInfo

Object

O:Optional

It is present if the mobile device is used to initiate the transaction.

GPS	gps	ANS	1-32	O:Optional	"+37.12/-121.23"	Components: +(-) latitude/+(-) longitude
SIM Card	simCard	Array	1-200	O:Optional		The mobile number of the SIM cards. The mobile phone may have more than one SIM card. Format: Country code (1-3 digits) + “-” + subscriber number
Application User ID	appUserID	ANS	1-64	O:Optional		An alias for the application user ID
User Enrollment Date	usrEnrolDate	N	6	O:Optional	"161230"	Format:YYMMDD.The date when the cardholder registers in the wallet.
IP Address	ipAddress	ANS	1-39	O:Optional		The public network IP address of the device
Reserved Mobile Number	reservedMobileNo	ANS	1-25	O:Optional	“86-13900000000”	The mobile number collected by the application when the user registered his account. The mobile application uses the reserved mobile number to verify the account user. The mobile number format is defined in [ITU-T E.164]. Components: Country code (1-3 digits) + “-” + subscriber number; If the country code is not present, UPI API will consider it as a Chinese mobile number.
Device Score	deviceScore	N	1	O:Optional	“5”	Valid Values: “1” to “5”. “5” indicates the device is the most reliable, and “1” indicates the device is the least reliable.
Bill Number	billNo	ANS	1-25	C:Conditional		The invoice number or bill number. It may be provided by the merchant or entered by the payer. It is present in Merchant-presented QRC payment and the ID "01" under template "62" exists in the Merchant-presented QRC.
Mobile Number	mobileNo	ANS	1-25	C:Conditional		The Mobile Number to be used for multiple use cases, such as mobile top-up and bill payment. It may be provided by the merchant or entered by the payer. The mobile number may be different from the payer mobile number, which will be passed to the Payee / Merchant as additional information. It is present in Merchant-presented QRC payment and the ID "02" under template "62" exists in the Merchant-presented QRC.
Store Label	storeLabel	ANS	1-25	C:Conditional		A distinctive value associated to a store. It may be provided by the merchant or entered by the payer. It is present in Merchant-presented QRC payment and the ID "03" under template "62" exists in the Merchant-presented QRC.
Loyalty Number	loyaltyNumber	ANS	1-25	C:Conditional		Typically, a loyalty card number. It may be provided by the merchant or entered by the consumer. It is present in Merchant-presented QRC payment and the ID "04" under template "62" exists in the Merchant-presented QRC.
Reference Label	referenceLabel	ANS	1-25	C:Conditional		Any value defined by the Merchant or Payee in order to identify the transaction. It may be provided by the merchant or entered by the consumer. It is present in Merchant-presented QRC payment and the ID "05" under template "62" exists in the Merchant-presented QRC.
Customer Label	customerLabel	ANS	1-25	C:Conditional		Any value identifying a specific consumer. It may be provided by the merchant or entered by the consumer. It is present in Merchant-presented QRC payment and the ID "06" under template "62" exists in the Merchant-presented QRC.
Terminal Label	terminalLabel	ANS	1-25	C:Conditional		A distinctive value associated to a terminal in the store. It may be provided by the merchant or entered by the consumer. It is present in Merchant-presented QRC payment and the ID "07" under template "62" exists in the Merchant-presented QRC.
Purpose of Transaction	trxPurpose	S	1-25	C:Conditional		Any value defining the purpose of the transaction. It may be provided by the merchant or entered by the consumer. It is present in Merchant-presented QRC payment and the ID "08" under template "62" exists in the Merchant-presented QRC.
Email Address of the Consumer	consumerEmail	S	1-100	C:Conditional		The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the consumer. It will not be verified in the payment procedure, but be provided to the Payee / Merchant as additional information. It is present in Merchant-presented QRC payment and the ID "09" under template "62" contains value "E" in the Merchant-presented QRC.
Address of the consumer	consumerAddress	S	1-100	C:Conditional		The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the consumer. It will not be verified in the payment procedure, but be provided to the Payee / Merchant as additional information. It is present in Merchant-presented QRC payment and the ID "09" under template "62" contains value "A" in the Merchant-presented QRC.
Mobile number of the consumer	consumerMobileNo	ANS	1-25	C:Conditional		The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the consumer. It will not be verified in the payment procedure, but be provided to the Payee / Merchant as additional information. It is present in Merchant-presented QRC payment and the ID "09" under template "62" contains value "M" in the Merchant-presented QRC.

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

R:Returned

"S00010340001034420171230235959000000"

It is used to match a response to its request. The value must uniquely identify any message that the institution initiates on any day. Format: “S”+ Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits).Transmission Date and Time shall be filled by Beijing time (UTC+8).

Merchant Category Code

mcc

M:Mandatory

"6012"

Merchant Country Code

merchantCountry

M:Mandatory

“156”

The genuine merchant country code shall be returned, which will be included in the settlement file.

Merchant Name

merchantName

ANS

1-25

M:Mandatory

"UnionPay International"

Merchant City

merchantCity

ANS

1-12

M:Mandatory

"Shanghai"

Transaction Amount

trxAmt

ANS

1-13

M:Mandatory

"101.10"

Transaction Currency

trxCurrency

R:Returned

"156"

Receiving Party IIN

receivePartyIIN

C:Conditional

"00030344"

The distinctive value associated to the Receiving Party which manages Payee’s account. It is present if the transaction is successful.

Settlement Key

settlementKey

C:Conditional

Settlement Date

settlementDate

C:Conditional

Format: MMDD; It is present if the transaction is successful.

Settlement Amount

settlementAmt

ANS

1-13

C:Conditional

It is present when transaction currency is different from settlement currency and the transaction is successful.

Settlement Currency

settlementCurrency

C:Conditional

It is present when transaction currency is different from settlement currency and the transaction is successful.

Settlement Conversion Rate

settlementConvRate

ANS

1-9

C:Conditional

It is present when transaction currency is different from settlement currency and the transaction is successful.

Cardholder Billing Amount

cardholderBillingAmt

ANS

1-13

C:Conditional

It is present when transaction currency is different from cardholder billing currency and the transaction is successful.

Cardholder Billing Currency

cardholderBillingCurrency

C:Conditional

It is present when transaction currency is different from cardholder billing currency and the transaction is successful.

Cardholder Billing Conversion Rate

cardholderBillingConvRate

ANS

1-9

C:Conditional

It is present when transaction currency is different from cardholder billing currency and the transaction is successful.

Conversion Date

conversionDate

C:Conditional

"1230"

Format: MMDD; It is returned if either "settlementAmt" or “cardholderBillingAmt”exists.

Retrieval Reference Number

retrievalReferenceNumber

C:Conditional

Returned in successful transaction.

Payment Reference Number (PAR)

par

C:Conditional

It is present when PAR is available.

Message Response

msgResponse

Object

None

Response Code	responseCode	AN	2	M:Mandatory	"00"	It contains a code that defines the response to a request.
Response Message	responseMsg	S	1-100	M:Mandatory	"Approved"	It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the payer of the payment outcome.
Error Detail	errorDetail	S	1-255	O:Optional	“The Issuer response is time out.”	It contains additional detail regarding the problem identified in the message. The information is only for debug purpose. It shall not be displayed to the customer, cashier, etc.

Interface description

For cross-border remittance and domestic P2P transfer, push purchase and push cash withdrawal, etc., the Sending Party initiates MSG_RESULT_INQUIRY request to the UPI API if the Institution does not receive the original message response within the time limit, or receives after the timeout.

Request Method

HTTP POST

Request Parameter

	Field name	Identifier	Type	Length	Request	Default value	Note
	Message ID	msgID	AN	37	M:Mandatory	"S00010340001034420171230235959000000"	It is used to match a response to its request. The value must uniquely identify any message that the institution initiates on any day. Format: “S”+ Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits). Transmission Date and Time shall be filled by Beijing time (UTC+8).
	Original Message ID	originalMsgID	AN	29	M:Mandatory	"S00010340001034420171230235959000000"	The same value as the “msgID” of the inquired message.

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

R:Returned

“S0001034420190711235959123456”

It is used to match a response to its request. The value must uniquely identify any message that the institution initiates on any day. Format: “S”+ Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits). Transmission Date and Time shall be filled by Beijing time (UTC+8).

Original Message ID

originalMsgID

R:Returned

“S0001034420190711235959123456”

The same value as the “msgID” of the inquired message.

Transaction Amount

trxAmt

ANS

1-13

C:Conditional

"101.10"

It is returned if the inquired message is successful and it exists in the inquired message.

Transaction Currency

trxCurrency

C:Conditional

"156"

It is returned if the inquired message is successful and it exists in the inquired message.

Receiving Party IIN

receivePartyIIN

C:Conditional

The distinctive value associated to the Receiving Party which manages Payee’s account. It is present if the inquired message is successful.

Settlement Key

settlementKey

C:Conditional

Merchant ID

merchantID

ANS

1-15

C:Conditional

It is returned if the inquired message is successful and it exists in the inquired message.

Merchant Category Code

mcc

C:Conditional

"6012"

It is returned if the inquired message is successful and it exists in the inquired message.

Merchant Country Code

merchantCountry

C:Conditional

“156”

It is returned if the inquired message is successful and it exists in the inquired message.

Merchant Name

merchantName

ANS

1-25

C:Conditional

"UnionPay International"

It is returned if the inquired message is successful and it exists in the inquired message.

Merchant City

merchantCity

ANS

1-12

C:Conditional

"Shanghai"

It is returned if the inquired message is successful and it exists in the inquired message.

Business Indication

businessIndication

C:Conditional

“A1”

Valid value: “07”: Cross-border Remittance Outside of Mainland China. “08” Domestic P2P Outside of Mainland China. “21”: Push Cash Withdrawal. “22”: Push Purchase. “A1”: Inbound China Remittance. It is returned if the inquired message is successful and it exists in the inquired message.

Settlement Date

settlementDate

C:Conditional

Format: MMDD It is returned if the inquired message is successful and it exists in the inquired message.

Settlement Amount

settlementAmt

ANS

1-13

C:Conditional

It is returned if the inquired message is successful and it exists in the inquired message.

Settlement Currency

settlementCurrency

C:Conditional

It is returned if the inquired message is successful and it exists in the inquired message.

Settlement Conversion Rate

settlementConvRate

ANS

1-9

C:Conditional

It is returned if the inquired message is successful and it exists in the inquired message.

Cardholder Billing Amount

cardholderBillingAmt

ANS

1-13

C:Conditional

It is returned if the inquired message is successful and it exists in the inquired message.

Cardholder Billing Currency

cardholderBillingCurrency

C:Conditional

It is returned if the inquired message is successful and it exists in the inquired message.

Cardholder Billing Conversion Rate

cardholderBillingConvRate

C:Conditional

It is returned if the inquired message is successful and it exists in the inquired message.

Conversion Date

conversionDate

C:Conditional

"1230"

Format: MMDD. It is present if either "settlementAmt" or “cardholderBillingAmt”exists

Retrieval Reference Number

retrievalReferenceNumber

C:Conditional

It is returned if the inquired message is successful and it exists in the inquired message.

Original Message Response

origMsgResponse

C:Conditional

It is present if the “originalMsgID” is presented in the request message

Original Message Response Code	origMsgResponseCode	ANS	1-20	C:Conditional		When the result of the message inquired is not available, the Message Status shall be “PG”. Otherwise, it shall be the “responseCode” of the original message. It is present if the “originalMsgID” is presented in the request message
Original Response Message	origResponseMessage	S	1-100	C:Conditional	"Timeout"	It shall be the “responseMessage" of the message inquired. It is present if "originalMsgResponseCode" is presented
Original Error Detail	origErrorDetail	S	1-255	O:Optional	“The Issuer response is time out.”	It contains additional detail regarding the problem identified in the message.

Message Response

msgResponse

M:Mandatory

Response Code	responseCode	AN	2	M:Mandatory	"00"	It contains a code that defines the response to a request.
Response Message	responseMsg	S	1-100	M:Mandatory	"Approved"	It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the payer of the payment outcome.
Error Detail	errorDetail	S	1-255	O:Optional	“The Issuer response is time out.”	It contains additional detail regarding the problem identified in the message. The information is only for debug purpose. It shall not be displayed to the customer, cashier, etc.

Interface description

For cross-border remittance, the Sending Party initiates EXG_RATE_INQUIRY request to the UPI API to obtain the currency conversion information between transaction currency and cardholder billing currency.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
Message ID	msgID	AN	29	M:Mandatory	"S00010340001034420171230235959000000"	It is used to match a response to its request. The value must uniquely identify any message that the institution initiates on any day. Format: “S”+ Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits). Transmission Date and Time shall be filled by Beijing time (UTC+8).
Transaction Amount	trxAmt	ANS	1-13	M:Mandatory	"101.10"	The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as decimal mark. When amount includes decimals, "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The value must include the transaction fee amount if it exists.
Transaction Currency	trxCurrency	N	3	M:Mandatory		A 3-digit numeric value, in line with ISO 4217, indicates the currency code of the transaction. The mobile application can display the transaction currency in a readable way, such as "RMB".

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

R:Returned

“S0001034420190711235959123456”

It is used to match a response to its request. The value must uniquely identify any message that the institution initiates on any day. Format: “S”+ Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits). Transmission Date and Time shall be filled by Beijing time (UTC+8).

Transaction Amount

trxAmt

ANS

1-13

R:Returned

"101.10"

Transaction Currency

trxCurrency

R:Returned

A 3-digit numeric value, in line with ISO 4217, indicates the currency code of the transaction. The mobile application can display the transaction currency in a readable way, such as "RMB".

Conversion Currency

conversionCurrency

R:Returned

Conversion Amount

conversionAmt

ANS

1-13

M:Mandatory

Conversion Date

conversionDate

M:Mandatory

Format: MMDD

Message Response

msgResponse

Object

M:Mandatory

Response Code	responseCode	AN	2	M:Mandatory	"00"	It contains a code that defines the response to a request.
Response Message	responseMsg	S	1-100	M:Mandatory	"Approved"	It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the payer of the payment outcome.
Error Detail	errorDetail	S	1-255	O:Optional	“The Issuer response is time out.”	It contains additional detail regarding the problem identified in the message. The information is only for debug purpose. It shall not be displayed to the customer, cashier, etc.

Interface description

For unintended push purchase, the UPI API sends REFUND request to the Receiving Party (Payer/Consumer) to return fund back into payer’s account.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
Message ID	msgID	AN	37	M:Mandatory	"U00010340001034420171230235959000000"	It is used to match a response to its request. The value must uniquely identify any message that the institution initiates on any day. Format: “U”+ Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits). Transmission Date and Time shall be filled by Beijing time (UTC+8).
Original Message ID	originalMsgID	AN	37	M:Mandatory		The same value as the “msgID” of the corresponding PRIMARY CREDIT message.
Forwarding IIN	forwardingIIN	AN	8	M:Mandatory	“00010344”	The distinctive value associated to the institution that connected to UPI.
Sending Party IIN	sendPartyIIN	AN	8	M:Mandatory	"00020344"	The distinctive value associated to the Sending Party (Merchant) which manages Payee’s account.
Local Transaction Date &Time	localTxnDateTime	N	10	M:Mandatory		Format: MMDDhhmmss
Card Information Capture Method	captureMethod	N	2	M:Mandatory	"94"	Valid Values: “01”: Manual; “94”: Merchant-presented QRC (barcode also), chip information excluded; Other values: Reserved; For manual input and NFC payment, filled with “01” in the request message.
Terminal Type	terminalType	N	2	M:Mandatory	“08”	Valid Values: “08”: Mobile Device; Other values: Reserved
Merchant Category Code	mcc	N	4	M:Mandatory	"6012"
Merchant Country Code	merchantCountry	N	3	M:Mandatory	“156”
Merchant Name	merchantName	ANS	1-25	M:Mandatory	"UnionPay International"	Filled with the value consistent with that returned in the original message.
Merchant City	merchantCity	ANS	1-12	M:Mandatory	"Shanghai"	Filled with the value consistent with that returned in the original message.
Transaction Amount	trxAmt	ANS	1-13	M:Mandatory	"101.10"	The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as decimal mark. When amount includes decimals, "." character shall be used to separate the decimals from the integer value, and the "." character may be present even if there are no decimals. The value must include the transaction fee amount if it exists.
Transaction Currency	trxCurrency	N	3	M:Mandatory	"156"	A 3-digit numeric value, in line with ISO 4217, indicates the currency code of the transaction. The mobile application can display the transaction currency in a readable way, such as "RMB". The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist.
Settlement Date	settlementDate	N	4	M:Mandatory		Format: MMDD
Settlement Amount	settlementAmt	ANS	1-13	C:Conditional		It is present when transaction currency is different from settlement currency and the transaction is successful.
Settlement Currency	settlementCurrency	N	3	C:Conditional		It is present when transaction currency is different from settlement currency and the transaction is successful.
Settlement Conversion Rate	settlementConvRate	ANS	1-9	C:Conditional		It is present when transaction currency is different from settlement currency.
Conversion Date	conversionDate	N	4	C:Conditional	"1230"	Format: MMDD. It is present if either "settlementAmt" or “cardholderBillingAmt”exists
Retrieval Reference Number	retrievalReferenceNumber	AN	12	M:Mandatory

Synchronous Response parameters

Filed name

Identifier

Type

Length

Request

Default value

Note

Message ID

msgID

R:Returned

"U00010340001034420171230235959000000"

It is used to match a response to its request. The value must uniquely identify any message that the institution initiates on any day. Format: “U”+ Sending Party IIN + Forwarding IIN + Transmission Date and Time (YYYYMMDDhhmmss) + System Trace Audit Number (6 numeric digits). Transmission Date and Time shall be filled by Beijing time (UTC+8).

Original Message ID

originalMsgID

R:Returned

The same value as the “msgID” of the corresponding PRIMARY CREDIT message.

Transaction Amount

trxAmt

ANS

1-13

R:Returned

"101.10"

Transaction Currency

trxCurrency

R:Returned

"156"

Message Response

msgResponse

Object

M:Mandatory

Response Code	responseCode	AN	2	M:Mandatory	"00"	It contains a code that defines the response to a request. Please refer to the Response Code and Message for the valid values.
Response Message	responseMsg	S	1-100	M:Mandatory	"Approved"	It contains the transaction result and the rejection reason if the transaction fails. The value of this field can be displayed on the mobile application to notify the consumer of the payment outcome.
Error Detail	errorDetail	S	1-255	O:Optional	“The Issuer response is time out.”	It contains additional detail regarding the problem identified in the message. The information is only for debug purpose. It shall not be displayed to the customer, cashier, etc.

Steps to Launch

1. Review and Sign MOU & NDA.

Note：MOU( Memorandum of Understanding)

NDA(Non-disclosure Agreement)

2. Sign membership application forms and settlement agreement, submit the membership application forms and related documents.

3. Receive LA and IIN assignment from UPI.

Note: LA(Letter of Authority)

4. Develop the system and operational requirements.

5. Preparation check and launch.

Please submit order in Support Center to contact us.

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