Open API >Online Payments >In-App Apple Pay (Indirect Mode)
In-App Apple Pay (Indirect Mode)
Online Payments Acquirer Internet Payment
UPI In-App Apple Pay (Indirect Mode) Payment provides SDK solutions for acquirers/gateways to support Apple Pay (Indirect Mode). UnionPay will provide SDK to secure users' card information and data.
API Introduction
API Introduction
What is it?

The API is based on ApplePay SDK for acquirer (Indirect Merchant). It contains back-end SDK for UPOP5.0/5.1 interface. Merhcant APP shall collect payment information and send it to the acquirer/gateway. Acquirer/gateway can initiate the transaction via the back-end interface to UPOP5.0/5.1. The back-end interface can be developed via the back-end SDK.


The pricing strategy of In-App transactions currently follows the UPI E-Commerce pricing strategy.


Key Features

UPI In-App Apple Pay (In-direct Mode) Payment provides a convenient and secure channel for the cardholder to finish the Apple Pay payment within the merchant APP without re-direction. The payment can be initiated by the acquirers/gateways via internet access.

Escpecially, In-App Apple Pay supports the calling of QuickPass to finish payment.

When to Use it?

UnionPay Apple Pay SDK will be used to help merchant provide the payment service. And the SDK will be resopnsible for securely collecting payment information and completing transaction.  

Who Use it?
Acquirers and Gateways
Where to Use it?
This API is available globally except for mainland China
Things to Know

1) In-App Payment shall support purchase, inquiry and back-end notification receival. Other transactions will be optional.


2) The In-App Apple Pay (In-direct Mode) Payment transactions can be processed via the back-end interface to UPOP5.0/5.1. Please note the transaction differences while using the testing URL and the production URL.


3) Certificate of testing environment is contained in the back-end SDK package. 


Flow Chart
Flow Chart

in-app Apple pay indirect流程图.png

1. Cardholder chooses Apple Pay in the merchant APP;

2. The merchant collects Apple Pay payment data and initiates a request message to the acquirer system;

3. The acquirer transfers the request to UnionPay Omnichannel Platform (UPOP);

4. UPOP transfers the transaction to UnionPay core processing system;

5. UnionPay core processing system converts FX rate and transfers the transaction to the issuer;

6. The issuer authorizes transaction and the response message goes back to the merchant over the same route.


API Reference
API Reference
  • Inquiry
  • Purchase
  • Purchase cancellation
  • Refund
  • Pre-authorization
  • Pre-authorization Cancellation
  • Pre-authorization Completion
  • Pre-authorization Completion Cancellation
Interface description
Inquiry transaction refers to when a transaction requestor (e.g. merchant, acquirer) sends inquiry information message to UPI system directly through the requestor server.
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
Version number version NS 5 M:Mandatory 5.1.0: Fixed value
Encoding method encoding ANS 1-20 M:Mandatory UTF-8: Default value
Certificate ID certId N 1-128 M:Mandatory The serial number of private key certificate for signature, which can be obtained through SDK is provided by UPI.
Signature signature ANS 1-1024 M:Mandatory Fill in message hash signature
Signature method signMethod N 2 M:Mandatory 01: RSA
Transaction type txnType N 2 M:Mandatory 00: Transaction state inquiry
Transaction sub-type txnSubType N 2 M:Mandatory 00: Default
Product type bizType N 6 M:Mandatory 000000: Default
Access type accessType N 1 M:Mandatory 1: Acquirer access
Acquiring Institution Identification Number acqInsCode AN 8-11 C:Conditional Applied if access type is acquirer access
Merchant ID merId AN 15 M:Mandatory The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant order number orderId AN 8-40 M:Mandatory Order number of queried transaction.Should not contain ‘-’ and ‘_’
Order time txnTime N M:Mandatory Transaction time of queried transaction. Format: YYYYMMDDhhmmss
Reserved field reserved ANS 1-1028 O:Optional Format is as follows: {variable name 1 = value1&variable name 2 = value2&variable name 3 = value3}, please refer to subfield description for details.
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Version number version NS 5 R:Returned 5.1.0: Fixed value
Signature signature ANS 1-1024 M:Mandatory Fill in message hash signature
Encoding method encoding ANS 1-20 R:Returned Fill in with the character encoding used for message
Signature method signMethod N 2 M:Mandatory 01: RSA
Transaction type txnType N 2 M:Mandatory Value: same as the queried transaction
Transaction sub-type txnSubType N 2 M:Mandatory Value: same as the queried transaction
Product type bizType N 6 R:Returned
Access type accessType N 1 R:Returned 1: Acquirer access
Acquiring Institution Identification Number acqInsCode AN 8-11 R:Returned Applied if access type is acquirer access
Merchant ID merId AN 15 R:Returned The unique identity code assigned by UnionPay when merchant access UPOP, namely Merchant ID.
Merchant order number orderId AN 8-40 M:Mandatory Order number of queried transaction.Should not contain ‘-’ and ‘_’
Order time txnTime N M:Mandatory Transaction time of queried transaction Format: YYYYMMDDhhmmss
Requestor reserved field reqReserved ANS 1-1024 O:Optional Return the requestor reserved field for the queried transaction
Reserved field reserved ANS 1-2048 C:Conditional Please refer to reserved field definition for details
Transaction query number queryId AN 21 M:Mandatory Query number of queried transaction
System Trace Audit Number traceNo N 6 M:Mandatory Returned by system.System assigns each transaction a System Trace Audit Number.
Transmission date and time traceTime N M:Mandatory Returned by system Format: MMDDhhmmss
Settlement date settleDate N C:Conditional The settlement related fields only returned by system for successful financial transaction.The value range is:MM: 1-12.DD: 1-31 Format: MMDD
Settlement currency settleCurrencyCode AN 3 C:Conditional Please refer to ISO4217.Note: UnionPay uses numeric currency code.
Settlement amount settleAmt N 1-12 C:Conditional Financial transaction returned by system.Settlement amount=transaction amount ×settlement conversion rate
Conversion Rate exchangeRate N 8 C:Conditional This field is only used when the transaction currency is different from the settlement currency.The format is right-justified without a decimal point. The number of decimal digits is indicated by the left most number. The digits from 2 to 8 indicate the value of the conversion rate.For example: 71212345 indicates that the conversion rate is 0.1212345.
Conversion date exchangeDate N C:Conditional Financial transaction returned by system.This field is only used when the transaction currency is different from the settlement currency.The value range is:MM: 1-12.DD: 1-31 Format: MMDD
Transaction currency currencyCode AN 3 M:Mandatory Value: Same as the queried transaction
Transaction amount txnAmt N 1-12 M:Mandatory Value: Same as the queried transaction
Original transaction response code origRespCode AN 2 C:Conditional Returned if transaction inquiry is successful
Original transaction Response information origRespMsg ANS 1-256 C:Conditional Returned if transaction inquiry is successful
Response code respCode AN 2 M:Mandatory For details please refer to Part IV A.1 response code
Response information respMsg ANS 1-256 M:Mandatory Fill in detailed Response information
Primary Account Number (PAN) accNo AN 1-1024 C:Conditional Returned based on configuration. If product type is Merchant-hosted, ExpressPay or MOTO, the account number must be decrypted through a private key.Returned last 4 digits of PAN number if the product type is Token payment.
Account attribute payCardType N 2 C:Conditional Returned based on configuration. The value is:00: Unknown.01: Debit account.02: Credit account.03: Quasi-credit account.04: Credit/Debit account.05: Prepaid account
Issuer institution identify mode IssuerIdentifyMode N 1 C:Conditional Returned for purchase and pre-authorization transaction:0: Authentication mode.1: Non-authentication mode
Payment card number payCardNo ANS 1-19 C:Conditional Applied for mobile payment purchase transaction,Returned based on merchant configuration.
Payment card name payCardIssueNa ANS 1-64 C:Conditional Applied for mobile payment purchase transaction,Returned based on merchant configuration.
Card-Present transaction information field cardTransData ANS 1-2048 C:Conditional Applied for card-present transactions. Please refer to 4.5.5 for details.Return sub-field IC card data ICCardData only in response message.
Public key certificate for Signature signPubKeyCert AN 2048 C:Conditional Return UnionPay public key certificate for signature when RSA is used as signature method
SDK Instruction
SDK Instruction

SDK Version

Operating Environment

JAVA

Eclipse+ jdk1.6.12u5 and above + Tomcat 6.0 and above

.NET

Visual studio 2010 and above + .NET framework 4.0 and above

PHPphp 5.3 and above


Steps to Launch
Steps to Launch

Step 1 – Certificate Application

Developers need to obtain three certificates – signature certificate, sensitive information encryption certificate and signature verification certificate before calling the interface. 

● Signature Certificate

Signature Certificate is used to sign or verify a transaction message. First create a message digest, and then use the digest to sign or verify the message. 

How to get signature certificate

1) For signature certificate of the testing environment - It can be obtained from ‘assets’ directory in the SDK directly.

2) For signature certificate of the production environment - UnionPay Business Operation Centre will send an email to the contacts in the application form after approval. The required serial number and license key will be presented in the email.

● Signature Verification Certificate

Signature Verification Certificate is used to verify a transaction response

How to get signature verification certificate

1) For UPOP 5.0 signature verification certificate of the testing environment – It can be obtained from ‘assets’ directory in the SDK directly.

2) For UPOP 5.0 signature verification certificate of the production environment - It can be obtained from ‘assets’ directory in the SDK directly.

3) For UPOP 5.1 signature verification certificate of the testing environment – It is carried in the UPOP reply message.

4) For UPOP 5.1 signature verification certificate of the production environment – It is carried in the UPOP reply message.

● Encryption Certificate

Encryption Certificate is used to encrypt the sensitive information in the UPOP request message.

How to get encryption certificate

1)  For UPOP 5.0 encryption certificate of the testing environment – It can be obtained from ‘assets’ directory in the SDK directly.

2)  For UPOP 5.0 encryption certificate of the production environment –It can be obtained from ‘assets’ directory in the SDK directly.

3)  For UPOP 5.1 encryption certificate of the testing environment – It can be obtained from ‘assets’ directory in the SDK directly.

4)  For UPOP 5.1 encryption certificate of the production environment – Merchant imitates inquiry message to UPOP system periodically (one time per day) to retrieve public key certificate update information. During encryption public key certificate updates, the UPOP system supports both new and old certificates, which last for one month. The UPOP system will return the latest encryption public key certificate and merchant server will replace it with local certificate.


Step 2 – SDK Integration and Configuration

To access the UPOP5.0/5.1 interface, we provide back-end SDKs of JAVA, PHP and .NET which package the fundamental functions such as signature & signature verification, HTTP interface request, etc. Please download the SDK of corresponding language and introduce it to your project.

Notice:

1)The final payment result must subject to the back-end notification from transaction inquiry interface. 

2) The back-end notification received by the acquirer/gateway system must pass the signature verification to ensure its validity. To learn more about the verification method, please refer to the notification.

3) After receiving back-end notification and passing signature verification, please send transaction inquiry request for transaction result according to 'orderId', 'txnTime', 'merId' in the notification.


FAQ and Documentation
FAQ and Documentation
Documents:
Response Code Reference
Response Code Reference
Response code Description
00 Success
01 Transaction failed. For details please inquire overseas service hotline.
02 System is not started or temporarily down, please try again later
03 Transaction communication time out, please initiate inquiry transaction
05 Transaction has been accepted, please inquire about transaction result shortly
06 System is busy, please retry it later.
10 Message format error
11 Verify signature error
12 Repeat transaction
13 Message transaction key element missing
30 Transaction failed, please try using other UnionPay card for payment or contact  overseas service hotline
31 Merchant state incorrect. The payment is not completed within the order timeout.
32 No such transaction right
33 Transaction amount exceeds limit
34 Could not find this transaction
35 Original transaction does not exist or state is incorrect
36 Does not match original transaction information
37 Max number of inquiries exceeded or too frequent operations
38 UnionPay risk constraint
39 Transaction is not within the acceptance time range
42 Balance deduction successful but transaction exceeded payment time limit
43 Business not allowed, please contact overseas service hotline for help.
44 Wrong number entered or business not opened, please contact overseas service hotline for help.
45 The original transaction has been refunded or cancelled successfully.
60 Transaction failure, for details, please inquire with your issuer
61 Card number entered is invalid, please double check and enter
62 Transaction failed, issuer does not support this merchant, please change to another bank card
63 Card state is incorrect
64 Card balance is insufficient
65 Error with PIN, expiration date, or CVN2 entered, transaction failure
66 Cardholder identity information or mobile number entered are incorrect, verification failure
67 Limit on number of PIN entry attempts exceeded
68 Your bank card currently does not support this business, please inquire with your bank or  overseas service hotline for help
69 Time limit on entry exceeded, transaction failure
70 Transaction has been redirected, waiting for cardholder input
71 Dynamic password or SMS verification code validation failure
72 You have not signed up for UnionPay card-not-present payment service at the bank counter or on your personal online bank, please go to a bank counter or access your online banking to activate it or contact overseas service hotline for help.
73 Payment card has exceeded expiration date
76 Requires encryption verification for activation
77 Bank card has not been activated for authenticated payment
78 Issuer transaction rights limited, for details please contact your issuer
79 The bank card is valid, but issuer does not support SMS verification
80 Transaction failed and the token has expired
81 Monthly accumulated transaction counter (amount) exceeded
82 PIN needs to be verified
84 PIN is required but not submitted
85 Transaction failed, the marketing rules are not met
86 QRC status error
88 QRC not found
89 No Token found, invalid TR status or invalid Token status
98 File does not exist
99 General error
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.