By continuing your navigation on our website, you consent to the use of cookies to provide you with better services. To learn more, read our cookies policy.
x
APIs
Products & Solutions
Partner
Support
Sign in
Search
International
中国站
Open API >Primary Credit Transaction >Primary Credit Transaction for Issuer
Primary Credit Transaction for Issuer
Primary Credit Transaction Issuer
Primary Credit Transaction for Issuer provides an easy, flexible and secure solution for issuers to authorize UnionPay primary credit transactions.
Sandbox Testing
API Introduction
API Introduction
What is it?

Traditionally issuers use 8583 format interface for UnionPay primary credit transaction authorization, which is time-consuming to develop and maintain. UPI Primary Credit Transaction Issuing Backend Interface, which uses JSON message format, serves as an easy and friendly alternative to 8583 interface, and supports multiple primary credit transaction scenarios including cross-border remittance, B2B payout, tax refund, P2P transfer, push purchase and push cash withdrawal, etc.

Key Features

Flexible

Supporting both internet and leased line connection.


Secure

Supported by well-developed security mechanism. 


Who Use it?
Issuer Partners that wants to launch UnionPay primary credit transaction business fast, easily and securely.
Where to Use it?
This API is available globally except for mainland China
Flow Chart
Flow Chart

发卡授权流程图.png

1. Acquirer initiates primary credit transaction to UPI system.

2. UPI system transfers the authorization request to issuer (in JSON format).

3. Issuer authorizes the transaction and responds to UPI (in JSON format).

4. UPI transfers transaction response to acquirer.
API Reference
API Reference
  • ISSUER_PRIMARY_CREDIT
  • ISSUER_PRIMARY_CREDIT_CONFIRMATION
Interface description
Primary Credit API is used for cash rebate, B2B payout or tax refund.
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
Message ID msgID AN 37 M:Mandatory "U0001034420171230235959000000" It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits)
Forwarding IIN forwardingIIN AN 8 M:Mandatory “00010344” The Identifier associate to the payment processor. If the transaction is initiated by the UNIONPAY API, this field shall be filled in with UNIONPAY API IIN. If the transaction is initiated by Gateway, PSP, Payment facilitator, etc., this field shall be filled in with the corresponding identifier assigned by UPI.
Sending Party IIN "sendPartyIIN" AN 8 M:Mandatory "00020344" The distinctive value associated to the Sending Party which manages Payer’s account.
Local Transaction Date &Time localTxnDateTime N 10 M:Mandatory Format: MMDDhhmmss
Card Information Capture Method captureMethod N 2 M:Mandatory ”01” Valid Values: • “00”: UNKNOWN; • “01”: MANUAL; • “03”: CONSUMER_PRESENTED_QRC(chip information included); • “04”: CONSUMER_PRESENTED_QRC(chip information excluded); • “05”: CONTACT; • “07”: NFC; • “10”: STORED_CREDENTIALS; • “93”: MERCHANT_PRESENTED_QRC(chip information included); • “94”: MERCHANT_PRESENTED_QRC(chip information excluded)
Terminal Type terminalType N 2 M:Mandatory “08” Valid Values: “03”: POS; “07”: PC; “08”: MOBILE; Reserved Values: “00”: UNKNOWN
Merchant ID merchantID ANS 1-15 M:Mandatory “ABCDE01” The distinctive value associated to the Merchant.
Merchant Category Code mcc N 4 M:Mandatory Convenience store is represented by "5411".
Merchant Country Code merchantCountry N 3 M:Mandatory "156"
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 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 AN 8 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.
Payment Facilitator ID (PF ID) “pfID” AN 8 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-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". The value must include the transaction fee amount if it exists.
Transaction Currency trxCurrency N 3 M:Mandatory "156" A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the transaction. The currency also applies to the "discount", "costAmount", and "trxFeeAmt" if they exist.
Fund Source fundSource N C:Conditional It is present if submitted by the Sending Party.Valid values：0 – cash.1 – debit card .2 – credit card.3 – account funds
Business Indication businessIndication AN “A1” M:Mandatory Valid value: "03": Cash Rebate "06": Tax Refund “14”: B2B Payout "07": Cross-border Remittance Outside of Mainland China "08" Domestic P2P Outside of Mainland China
Receiving Party IIN “receivePartyIIN” AN 8 M:Mandatory The distinctive value associated to the Receiving Party.
Settlement Date settlementDate N 4 M:Mandatory "1230" Format:MMDD
Settlement Currency settlementCurrency N 3 C:Conditional “840” A 3-digit numeric value, as defined by [ISO 4217], that indicates UNIONPAY API’s settlement currency. Present when the " settlementCurrency " has a different value from "trxCurrency"
Settlement Amount settlementAmt ANS 1-13 C:Conditional “15.17” 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. Present when the " settlementCurrency " has a different value from "trxCurrency"
Settlement Conversion Rate settlementConvRate ANS 1-9 C:Conditional "71212345" The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the " settlementCurrency " has a different value from "trxCurrency"
Cardholder Billing Currency cardholderBillingCurrency N 3 C:Conditional “840” A 3-digit numeric value, as defined by [ISO 4217], that indicates the currency code of the card account. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency"
Cardholder Billing Amount cardholderBillingAmt ANS 1-13 C:Conditional “15.17” 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. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency"
Cardholder Billing Conversion Rate cardholderBillingConvRate ANS 1-9 C:Conditional "71212345" The 1st digit indicates the number position where the decimal point should be moved from the right (allowed values are 0–7). The 2nd-final digits indicate the value of the conversion rate, and are right justified with no decimal point. For example, 71212345 indicates that the conversion rate is 0.1212345. Present when the "cardholderBillingCurrency" has a different value from "trxCurrency"
Conversion Date conversionDate N 4 C:Conditional "1230" Present if either "settlementAmt" or “cardholderBillingAmt”exists. Format: MMDD
Retrieval Reference Number "retrievalReferenceNumber" AN 12 M:Mandatory
Payment Reference Number (PAR) par AN 29 C:Conditional It is present when PAR is available.
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 PAN Expiry Date payeePanExpiryDate N 4 O:Optional "2203" Expiration date of the account number or token in YYMM format.
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"
Encrypted Data encData Object M:Mandatory
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
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.
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. Format: Country code (1-3 digits) + “-” + subscriber number
IP Address ipAddress ANS 1-64 O:Optional The public network IP address of the device
Token Information tokenInfo Object C:Conditional
Token Information Verification Indicator tokenVerifyIndicator AN 1 C:Conditional "tokenVerifyIndicator" Token Information Verification Indicator
Token token AN 1-19 C:Conditional Token generated by the TSP. Present if it is a token-related transaction.
Token Expiry Date tokenExpiryDate AN 4 C:Conditional The expiry date of a Token that is generated by the TSP. Present if it is a token-related transaction.
Token Assurance Level tokenAssuranceLevel AN 1-2 C:Conditional The Token Assurance Level is defined by the TSP based on the risk assessment. Valid Values: 0 to 99
Token Domain Identification tokenDomainID N 2 C:Conditional The Token Domain Identification indicates the application scenarios which are provided by the TR. Valid Values: 01: SE; 02: HCE; 03: QR Code; 04: Card-On-File (COF); 05: Digital wallet; 06: Chip or Magstripe Card; Present if it is a token-related transaction.
TRID trID AN 8-11 C:Conditional TRID is a unique number assigned by the TSP during TR Registration. Present if it is a token-related transaction.
Product Category productCate ANS 1 C:Conditional The Product Category is provided by the TR during Token Request. UnionPay system will de-tokenize the transaction and forward to the Issuer with this value in a Payment Token Transaction. Valid Values: 1: Mobile Payment; Present if it is a token-related transaction.
Product Sub-category productSubCate B 24 C:Conditional Binary form of data. The 10th-12th bytes of 9F63. For the definition of 9F63, please refer to UnionPay Integrated Circuit Card Specifications. Present if it is a token-related transaction.
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Message ID msgID AN 37 R:Returned "U0001034420171230235959000000" It is used to match a response to its request. The value must uniquely identify any message that the UNIONPAY API initiates on any day. The value in the response must match the value in the request. Components: “U” + Acquirer IIN + Forwarding IIN+ Transmission Year (YYYY) + Transmission Date and Time (MMDDhhmmss) + System Trace Audit Number (6 numeric digits)
Fund Source fundSource N M:Mandatory It is present if submitted by the Sending Party.Valid values：0 – cash.1 – debit card .2 – credit card.3 – account funds
Business Indication businessIndication AN “A1” C:Conditional Valid value: "03": Cash Rebate "06": Tax Refund “14”: B2B Payout "07": Cross-border Remittance Outside of Mainland China "08" Domestic P2P Outside of Mainland China
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. 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 by the Merchant to notify the consumer of the payment outcome. Refer to the Response Code and Message for details.
Error Details 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.
Security Requirement
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
Sequence Chart

时序图.png

1. The UnionPay API system sends the ISSUER_PRIMARY_CREDIT request to the payee’s account management institution, i.e. the Receiving Party. 

2. The Receiving Party confirms the accuracy and legitimacy of the payee information and conducts necessary risk controls checking, then responds to the UnionPay API. 

Exceptional flows: 

1. The UnionPay API does not receive the ISSUER_PRIMARY_CREDIT response message within 40s, the UnionPay API initiates the ISSUER_PRIMARY_CREDIT_CONFIRMATION request message to the Receiving Party.

2. The Receiving Party returns the ISSUER_PRIMARY_CREDIT_CONFIRMATION response message to the UnionPay API.
Steps to Launch
Steps to Launch

If you are UPI issuers member, you need to fill in the Application Form of API Service Product with Terms and Conditions.

When the business goes online, the card issuing bank shall conduct key exchange with UnionPay international to ensure the transaction security, and the card issuing bank shall submit system parameters such as IIN and API called address

Please contact Developer Operation Team by submitting orders
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.
©Copyright 2002 - 2022. All rights reserved