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 <<paymentGateway>>. 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
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=APPROVEDresult=SUCCESS |
The payment is successful. |
response.gatewayCode=PENDINGresult=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_ERRORresult=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_OUTresult=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 <<paymentGateway>> 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.