Main flows

To integrate a merchant's system with Alipay to run the Transaction QR Code payment, the merchant is required to implement functions of payment, cancel, query, and refund. These function flows are respectively explained in this chapter.

Pre-create flow

This service is able to create a transaction while the customer's information (such as the barcode from customer as the barcode payment) is absent, and this feature meets the requirement of the Transaction QR Code Payment.

The following figure illustrates the Transaction QR Code payment flow.

Notes:

1. For the merchant server's first HTTP request, the service name should be alipay.acquire.precreate (PRECREATE).
2. The parameter values for calling the precreate service are encapsulated in the first HTTPs request data, including the signature data.
3. The PRECREATE service request will fail if either the signature is invalid or other compulsory parameter values are absent or illegal.
4. After calling the PRECREATE and displaying the QR Code to a customer, the merchant server shall wait an Alipay's asynchronous notification on the close 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.
5. In following cases, the merchant server shall call the alipay.acquire.cancel service to cancel the whole transaction.

1、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;

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

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

6. 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).
7. If the CANCEL service response is not with SUCCESS, the merchant system should retry CANCEL call.
8. For the list of parameters and their values of the PRECREATE and CANCEL service, please refer the corresponding interface API for detail.
9. 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 side.
10. According to Alipay latest rules, the secondary_merchant_id (the second-tier merchants of the acquirer or the sub brands of the direct-integrated merchants) and store_id info (the serial number of the store under a merchant) must be passed to identify the location of a transaction. With the seller_id, secondary_merhcant_id, and store_id fields, a specific store can be uniquely targeted.

Cancel flow

During the payment process of a transaction, it is possible to encounter issues such as system exception or network accessibility. In such a scenario, you need to reverse the transaction.

The following figure illustrates the work flow.

To implement this reversing, we would like to highlight the notes of below:

1. In this integration, please use the CANCEL to reverse a transaction, and the interface name is: alipay.acquire.cancel.
2. For a transaction that has been successfully paid, the CANCEL is able to refund the transaction within the transaction day (GMT+8), and the transaction status will change to TRADE_CLOSED. For transactions made around the cutoff time, a 15-minute buffer is provided to cancel the transaction.
3. Comparing with the REFUND service, if a transaction can be refunded by this CANCEL interface, the transaction fee that hass been charged by Alipay will always be refunded as well.
4. For a transaction has encountered technical issues during making the payment, the CANCEL is able to roll back all the actions have been performed in the Alipay system regarding the specific transaction.
5. For the full list of parameters and error code of this CANCEL service, please refer the interface API document for details.
6. 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.

Refund flow

For a transaction that has been successfully paid, the customer can request the merchant for refunding as long as the refunding period is still valid, and the merchant can make use of the refunding interface to achieve the goal.

The following figure illustrates the work flow.

For the integration of the refunding service, we would like to highlight:

1. The refund service name is: alipay.acquire.overseas.spot.refund;
2. Alipay supports 2 refund methods, asynchronous refund and synchronous refund, specified by is_sync parameter. is_sync=Y for synchronous refund, and is_sync=N for asynchronous refund.          Synchronous refund: Alipay makes the refund in real-time, and returns the result immediately. Asynchronous refund: Alipay will first response success, which means Alipay 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.
3. The refunding service is only applicable to a transaction that has been successfully paid;
4. The refunding of a transaction can be full or partial, i.e. the refunding amount can respectively be the same as or less than the original transaction amount that has been paid;
5. Regarding whether Alipay will return the charged fee of the original transaction, it depends on your contract with Alipay.
6. Comparing with the cancel interface (alipay.acquire.cancel), this service does not impose the 24-hours constraint, i.e. the merchant server can invoke this service at any time that between the moment when the transaction was paid and the time before the refunding period expires;
7. If a refunding request encounters a failure, please retry for a reasonable number of times. 

Query flow

You can query the status of a transaction order by using the query interface.

The following simplified flow shows the main process after calling the query interface:

For more information about the parameters and error codes, see The Query Interface.

Notes:

• 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 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.