Open API >Payment >In-APP (iOS) Payment
In-APP (iOS) Payment
Payment Merchant Acquirer
UPI In-APP (iOS) Payment provides SDK solutions for merchants APP to support SecurePay in-APP on iOS system. UnionPay will provide SDK to ensure the security of card information and data.
API Introduction
API Introduction
What is it?

The API is based on UninonPay Payment Control SDK (iOS). It contains the APP SDK and the back-end SDK. Merhcant APP shall invoke the APP SDK to complete purchase transaction. The APP SDK will collect payment information to complete the purchase transaction at the front-end. Other transactions are all back-end ones which can be done 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 (iOS) Payment can provide a convenient and secure channel for the cardholder to finish the payment within the merchant APP without re-direction. It supports SecurePay in-APP. The payment can be initiated by the merchant directly or by the gateway/acquirer via internet access.

When to Use it?

UPI In-APP (iOS) Payment will be used to help merchant provide the payment service. And the UnionPay SDK will be resopnsible for securely collecting the payment information and completing transction.  

Who Use it?
Acquirers, Gateways, Merchants
Where to Use it?
Oversea markets
Things to Know

1) In-APP Payment shall support puchase, inquiry and receiving back-end notification. Other transctions will be optional.


2) Merhcant APP shall invoke UnionPay SDK to complete purchase transaction. The SDK will collect payment information to complete the purchase transaction at the front-end. Other transactions are all back-end transactions which can be done via the back-end interface to UPOP5.0/5.1. Please note the differece between front-end transaction and back-end transaction while using the testing URL and the procution URL.


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


Flow Chart
Flow Chart

ios.png

API Reference
API Reference
  • Inquiry
  • Purchase
  • Purchase cancellation
  • Refund
  • Pre-authorization
  • Pre-authorization Cancellation
  • Pre-authorization Completion
  • Pre-authorization Completion Cancellation
Interface description
Inquiry
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 0: Merchant direct access1: 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-2048 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 0: Merchant direct access1: 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 transactionShould 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 Required for Merchant-presented QRC PaymentUPOP will return QRC information and discount information (if any) to acquirers/merchant.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-12DD: 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 systemThis field is only used when the transaction currency is different from the settlement currency.The value range is:MM: 1-12DD: 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
Account attribute payCardType N 2 C:Conditional Returned based on configuration. The value is:00: Unknown01: Debit account02: Credit account03: Quasi-credit account04:Credit/Debit account05: Prepaid account
Issuer institution identify mode IssuerIdentifyMode N 1 C:Conditional Returned for purchase and pre-authorization transaction:0: Authentication mode1: 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.
Public key certificate for Signature signPubKeyCert AN 2048 C:Conditional Return UnionPay public key certificate for signature when RSA is used as signature method
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

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 done the application process. 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 can be obtained from ‘assets’ directory in the SDK directly.


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 first and introduce it to your development project.

Notice:

1)Front-end notification can only be taken as reference, the final payment result must subject to the back-end notification from transaction inquiry interface. 

2) The front-end/back-end notification received by the merchant system must pass the signature verification to ensure it is sent by UnionPay. The verification method please refers to the notification.

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


  • Contact Us
  • If you have any further questions, please register and submit order in your user center.