UnionPay SecurePay Payments

UnionPay International through UnionPay Online Payment (UPOP), a global payment system for e-commerce transactions, offers UnionPay SecurePay as a service that allows payers to shop online using their UPOP SecurePay account on the UnionPay SecurePay website.

UnionPay SecurePay is a supported browser payment method in the MasterCard Payment Gateway. This page describes integration details specific to UnionPay SecurePay. It's recommended that you read the integration guidelines for browser payments, before building a UnionPay SecurePay integration.

Prerequisites

To offer UnionPay SecurePay as a payment method via the MasterCard Payment Gateway:

You must be boarded onto UPOP through your payment service provider.
Once configured with UPOP, your merchant profile on the MasterCard Payment Gateway must be configured by your payment service provider using the details of your account with UPOP.
Your checkout pages must comply with UnionPay SecurePay's branding requirements. See UnionPay International Acceptance Guide for e-Commerce merchants.

UnionPay SecurePay Integration

UnionPay SecurePay via Hosted Checkout

With Hosted Checkout integrations version 34 and later, UnionPay SecurePay is automatically available when your payment service provider has configured the acquirer link for UnionPay SecurePay.

If you use the interaction.timeout field to limit the time a payer has to complete their order, when the time remaining before the payment expires is less than 840 seconds, the payer will no longer be offered the possibility to select UnionPay SecurePay as a payment method in Hosted Checkout.

For details, see Browser Payments via Hosted Checkout Integration.

UnionPay SecurePay via Direct Payment

Choose Direct Payment integration if you want to offer UnionPay SecurePay payment method on your own checkout page.

UnionPay SecurePay is supported from API version 34 onwards.

Make an Initiate Browser Payment request where sourceOfFunds.type = UNION_PAY. For other details, see Browser Payments via Direct Payment Integration.

How to Interpret the Transaction Result

The table below shows the transaction response codes for the possible scenarios you may encounter after initiating a UnionPay SecurePay browser payment.

Scenario	Retrieve Transaction/Retrieve Order Response
TRANSACTION SUCCESSFUL
The payment is successful.	`browserPayment.interaction.status=COMPLETED` `response.gatewayCode=APPROVED`
TRANSACTION NOT SUCCESSFUL
The payment was declined by the acquirer.	`browserPayment.interaction.status=COMPLETED` `response.gatewayCode=DECLINED`
The payment was not successful, as the acquirer was unable to process it.	`browserPayment.interaction.status=COMPLETED` `response.gatewayCode=ACQUIRER_SYSTEM_ERROR`
The MasterCard Payment Gateway was unable to initiate the UnionPay SecurePay payment successfully.	`browserPayment.interaction.status=N/A` `response.gatewayCode=SYSTEM_ERROR`
The MasterCard Payment Gateway has received the payer's browser and redirected it to UnionPay SecurePay. No payment has happened within 2 hours. Any redirect requests for this payment are rejected by the MasterCard Payment Gateway.	`browserPayment.interaction.status=REDIRECTED_TO_PROVIDER` `response.gatewayCode=DECLINED`
The MasterCard Payment Gateway did not receive a redirect of the payer's browser from the merchant within 24 hours. No payment has occurred, and any redirect requests for this payment are rejected by the MasterCard Payment Gateway.	`browserPayment.interaction.status=INITIATED` `response.gatewayCode=TIMED_OUT`
TRANSACTION RESULT NOT YET KNOWN (IN PROGRESS)
The transaction has successfully been initiated in the gateway. The gateway has not yet received the payer's browser from the merchant for redirection to UnionPay SecurePay. No payment has happened yet.	`browserPayment.interaction.status=INITIATED` `response.gatewayCode=SUBMITTED`
The gateway has received the payer's browser and redirected it to UnionPay SecurePay. No payment has happened yet.	`browserPayment.interaction.status=REDIRECTED_TO_PROVIDER` `response.gatewayCode=SUBMITTED`
The gateway has returned the payer's browser back to the merchant. The gateway is currently attempting to find out about the success or otherwise of the payment.	`browserPayment.interaction.status=RETURNED_TO_MERCHANT` `response.gatewayCode=SUBMITTED`
The gateway was unable to find out about the success or otherwise of the payment. The gateway may still find out and update the transaction. You can follow up with a Retrieve Transaction request (as the gateway may have found out the result) or use the gateway's webhook notifications (if you have subscribed).	`browserPayment.interaction.status=RETURNED_TO_MERCHANT` `response.gatewayCode=UNKNOWN`
TRANSACTION STATUS UNKNOWN
The gateway was unable to find out about the success or otherwise of the payment. The gateway will no longer attempt to find out. You must contact the acquirer to find out the result.	`browserPayment.interaction.status=N/A` `response.gatewayCode=UNKNOWN`

Captures and Refunds

You can perform subsequent Captures or Refunds on UnionPay SecurePay orders using API Capture/Refund operations or via Merchant Administration.

Voids

You can perform Void transactions on UnionPay SecurePay orders using the API Void operation or via Merchant Administration. Only Authorize, Capture, and Pay transactions are supported for voids.

Testing Your Integration

The MasterCard Payment Gateway provides a UnionPay SecurePay Emulator that allows you to test your UnionPay SecurePay integration.

Troubleshooting and FAQs

Why is the card number not returned in the Retrieve Transaction response?

Your merchant account at UPOP can be configured to not return the card number. In this case, you will not see a card number returned in the Retrieve Transaction response. Contact your payment service provider if you wish to change this configuration at UPOP.

Why don't I see the card scheme and card brand returned for a successful UnionPay SecurePay payment?

If the MasterCard Payment Gateway was unable to identify the card scheme and card brand associated with the payer's card then Retrieve Transaction returns sourceOfFunds.provided.card.scheme=OTHER and sourceOfFunds.provided.card.brand=UNKNOWN.