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.precreate)

You can use this interface to create a pre-order and ask the Alipay server to generate a QR code for collecting payments. When you integrate the payment interface, pay attention to the following items:

1. The parameter values for calling the precreate service are encapsulated in the first HTTPs request data, including the signature data.
2. The precreate service request fails if either the signature is invalid or other compulsory parameter values are absent or illegal.
3. After calling the precreate interface and displaying the QR Code to a customer, the merchant server need to wait for an Alipay asynchronous notification of the transaction. And, the server should set up a time out mechanism: if the merchant server does not receive the notification within a time interval (60 seconds is recommended), the transaction should be failed.
4. In the following cases, the merchant server can call the alipay.acquire.cancel interface to cancel the whole transaction.

      a、During the pre-creating period, if the Alipay system service returns a message of failure or the            final payment staus (after customer scan the Transaction QR Code) is not a SUCCESS;

      b、The merchant server receives a time_out (60 second is recommended) for Alipay’s asynchronous        notification;

      c、During the whole payment process, if the cashier attempts to terminate the payment.

• The CANCEL service is able to roll back a transaction thoroughly no matter what the transaction’s current status is. And it is important to note that this service only works within the same transaction day (GMT+8).
• If the CANCEL service response is not with SUCCESS, the merchant system should retry CANCEL call.
• For the list of parameters and their values of the PRECREATE and CANCEL service, please refer the corresponding interface API for detail.

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.