AlipayHKAlipayHKDOCS

Implementing APIs

Alipay HK does not recommend any order for implementing the APIs. However, Alipay HK requires the integrator to implement all APIs listed in the following sections.

The payment interface (alipay.acquire.overseas.spot.pay)

Payment basics

For Alipay HK barcode payment, the default payment timeout period is 3 minutes, which starts when the transaction is created.

Implementing APIs

For each transaction, an intermediate status WAIT_BUYER_PAY and two final statuses TRADE_SUCCESS / TRADE_CLOSED exist. Merchants must ensure that each transaction is in the final status, and in addition the transaction status must be consistent at merchant system, cashier side, and Alipay HK side.

Payment modes

The following two modes exist in barcode payment. Merchants must integrate both modes to ensure that all payments can be collected smoothly:

  • Offline mode: In this mode, the network connection from user side is not required. After the code is scanned, the payment interface can be invoked to complete the payment.
  • Offline to online mode: For security reasons or regulatory requirements, users might be prompted to enter a payment password or equivalent key (touchID, faceID, etc.) to complete the payment. The network connection is required in the user side. In the offline to online mode, the payment interface first returns the UNKNOWN result. After receiving the result, the merchant must call the query interface to poll the payment result.

Alipay HK internal transactions will timeout in 3 minutes by default. Therefore, if the transaction status is still WAIT_BUYER_PAY after 3 minutes, the transaction is automatically closed. However, in real life, the cashier might not wait for 3 minutes. Merchants can set different timeout periods according to specific business requirements.

For example, merchants can set the timeout period to 60 seconds. Within this period, the merchant system will poll the result every 3-5 seconds through the QUERY interface. If TRADE_SUCCESS or TRADE_CLOSED received, the cashier will then be notified with the result. If still WAIT_BUYER_PAY received in 60 seconds, the CANCEL interface must be called to force the transaction to close.

Note:

Sometimes, the cashier might unable to initiate the automatic correction. In this case, a background job must be configured in partner's system to perform the auto-correction for transactions of the status WAIT_BUYER_PAY, and the timeout period can be slightly longer than that set in the cashier side.

Payment information

According to Alipay HK latest rules, the secondary_merchant_id and store_id info must be passed to identify the location of a transaction.

  • The secondary_merchant_id field represents the second-tier merchants of the acquirer or the sub brands of the direct-integrated merchants.
  • The store_id field represents the serial number of the store under a merchant.

With the partner_id, secondary_merhcant_id, and store_id fields, a specific store can be uniquely targeted.

The cancel interface (alipay.acquire.cancel)

You can call the cancel interface to cancel only transactions of the day in Beijing time. For transactions made around the cutoff time, a 15-minute buffer is provided to cancel the transaction.

The cancel interface will return success in following scenarios:

  • The transaction is not created successfully.
  • The transaction is created but not paid. In this case, the transaction will be forced to close, and customers cannot continue to pay.
  • The transaction is paid. In this case, the transaction will be refunded, and the transaction status will change to TRADE_CLOSED.

The refund interface (alipay.acquire.overseas.spot.refund)

Merchants must integrate the full refund or partial refund functions based on the actual business requirements, and then update the corresponding reconciling processes accordingly.

Alipay HK supports 2 refund methods, asynchronous refund and synchronous refund, specified by the is_sync parameter. is_sync=Y for synchronous refund, and is_sync=N for asynchronous refund.

  • Synchronous refund: Alipay HK makes the refund in real-time, and returns the result immediately.
  • Asynchronous refund: Alipay HK will first response success, which means Alipay HK has recorded a refund request and accepted it. Then the refund transactions will be batch processed at 23:00:00 GMT+8 on the transaction day. Retry till success.

The query interface (alipay.acquire.overseas.query)

For payment that has result_code = UNKNOW, the query processes must be initiated to obtain the actual transaction status. Before calling the query interface, merchants can check the transaction details through the backend system, or by scanning the code on user’s Alipay HK app or receipts.

For transactions with the status WAIT_BUYER_PAY, wait till timeout (3 minutes by default), and then call the query interface again to obtain the final transaction status.