Alipay In-Store Payments

Alipay In-Store is a payment method from China that allows customers to purchase goods in store, in China and abroad, using payment barcodes generated in their Alipay mobile wallet application. The barcodes from the payer's wallet are scanned on the merchant's POS terminal to initiate the payment. The payment amount is debited from the balance available in the payer’s Alipay wallet.

Alipay In-Store is a supported non-card payment method in the Mastercard Payment Gateway. This page describes integration details specific to Alipay In-Store.

Prerequisites

Before you begin integrating Alipay In-Store in your environment, ensure that you have:

  • Registered your merchant account with your local payment method aggregator.
  • Configured your gateway merchant profile using the account details provided by your local payment method aggregator, and your Alipay In-Store account details — StoreID and StoreName.

Alipay integration with the gateway only supports:

  • AUD, CAD, EUR, GBP, HKD, SGD, USD currencies.

Note that the gateway only supports Alipay for cross-border merchants, i.e., international merchants entering the Chinese market and Chinese tourists abroad that want to pay with Alipay. The gateway does not allow processing CNY natively for Chinese-domiciled merchants.

In the case of cross-border merchants:

  • The order amount will be presented to the payer (by the gateway) in the processing currency (e.g. EUR).
  • The payer will be debited by Alipay in CNY and will be charged for the currency conversion.
  • The merchant will be settled by the local payment method aggregator in EUR.

Alipay In-Store Payment Integration

Alipay In-Store is supported from API version 50 onwards, and only via the Pay operation.

Make a Pay request where sourceOfFunds.type = ALIPAY and transaction.source = PAYER_PRESENT. In addition, you must provide the following fields in the Pay request:

  • sourceOfFunds.provided.alipay.payerCode: Payer code is a one-time code used by Alipay to identify the payer. It is generated by the Alipay wallet app on the payer's mobile device.
  • posTerminal.store.id: Your unique identifier for the specific store or business location where the transaction took place.
  • posTerminal.store.name: Your name for the specific store or business location where the transaction took place.

How to Interpret the Transaction Result

The table below shows the transaction response codes for the possible scenarios you may encounter after initiating an Alipay In-Store payment.

Retrieve Transaction Response
What This Means...
response.gatewayCode=APPROVED
result=SUCCESS		 The payment is successful.
response.gatewayCode=PENDING
result=PENDING
 The gateway is waiting for a notification from the acquirer about the payment result. Try RETRIEVE_TRANSACTION again later or listen to notifications from the gateway.
response.gatewayCode=DECLINED or ACQUIRER_SYSTEM_ERROR
result=FAILURE		 The payment was declined. Offer the payer the option to try another payment method.
In the case of an ACQUIRER_SYSTEM_ERROR you may want to inquire with the acquirer the reason for payment failure, or you can try RETRIEVE_TRANSACTION again.
response.gatewayCode=TIMED_OUT
result=FAILURE		 Treat this as a declined payment. The gateway will make any attempt to ensure the transaction was not successful or will revert the transaction.

Refunds

You can refund Alipay In-Store payments in part or in full. You must be configured for refunds on the Mastercard Payment Gateway and on your merchant account at the local payment method aggregator.

Testing Your Integration

Once you finish building the integration between the POS system and the gateway and set up your account with the local payment method aggregator, you should test your integration using your test merchant profile (your merchant ID starting with 'TEST').

Testing the Pay Request

You can use the order.reference field when making a Pay request to trigger different values for response.gatewayCode. The table below shows the values you can send in the order.reference field and the corresponding transaction response codes.

order.reference response.gatewayCode response.acquirerCode transaction.funding.status order.status
TEST-SUCCEED APPROVED SUCCEEDED FUNDING_ASSURED CAPTURED
TEST-SUCCESS-INIT SUBMITTED PENDING IN_PROGRESS INITIATED
TEST-FAIL-DECLINE DECLINED FAILED : REMOTE_DECLINE NON_FUNDED FAILED
TEST-FAIL-TIMEOUT ACQUIRER_SYSTEM_ERROR FAILED : TIMEOUT NON_FUNDED FAILED
TEST-FAIL-NOTFOUND DECLINED FAILED : INPUT_DATA NON_FUNDED FAILED
TEST-TIMEOUT TIMED_OUT N/A NON_FUNDED FAILED

Testing the Refund Request

You can also make a Refund request to test refunds on a successful Pay test transaction. The order.status will return as REFUNDED in the transaction response for a successful refund.

Copyright © 2023 Mastercard