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.commerce.qrcode.create)

The merchant can request to generate a static QR code by the interface alipay.commerce.qrcode.create. This interface requires to input a notification URL, to which Alipay will send a notification with transaction status after a successful payment. 

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.