Trade status

This document describes the field trade_status, which is used to represent the status of Alipay payment product transactions. In addition, some best practices on how to handle the transaction statuses are provided.

In-store Payment

trade_status is used to describe the status of an In-store Payment transaction in the specific interfaces. Possible values are:

• WAIT_BUYER_PAY: The transaction is created and is waiting for the customer to pay.
• TRADE_SUCCESS: The transaction is paid and remains refundable. This status persists even if partial refunds occur.
• TRADE_CLOSED: This value is used in the following scenarios.

• The transaction is not paid within the default time limit in Alipay system, for example, 3 minutes, and is automatically closed.
• The transaction is cancelled.
• The transaction is fully refunded.

• TRADE_FINISHED: The transaction is paid and cannot be refunded, because the refund period is expired.

The relationships between the transaction statuses are illustrated in the following figure:

Figure 1. In-store Payment transaction status

Related interfaces

For In-store Payment transactions, trade_status is returned by the following interfaces:

Rules of trade_status of In-store Payment also apply to Pre-auth Payment, and trade_status is returned by the following interfaces:

Note

For alipay.acquire.overseas.query, the parameter that is used to describe the transaction status is alipay_trans_status.

Best practices for keeping transactions in final stauts

The best practices in this section applies to Barcode Payment and Transaction QR Code Payment.

For each In-store Payment transaction, an intermediate status WAIT_BUYER_PAY and three final statuses TRADE_SUCCESS, TRADE_FINISHED, and TRADE_CLOSED exist. Merchants must ensure that each transaction is in the final status. In addition, the transaction status must be consistent at merchant system, cashier side, and Alipay side.

By default, an In-store Payment transaction is automatically closed in 3 minutes if the payment is not completed. However, in real life, the cashier might not wait for 3 minutes. Merchants can set different time limit according to specific business requirements.

Specifically, for Barcode Payment and Transaction QR Code Payment, you can take the following actions to ensure that the transactions reach the final status:

• If the transaction result is not returned in a certain period, for example, 5 seconds after the transaction is created, use QUERY interface to poll the result once every 3-5 seconds.
• Set a timeout period, for example, 60 seconds, and keep polling the result before the timeout period expires.
• If TRADE_SUCCESS or TRADE_CLOSED is received during the query, the cashier will then be notified of the result.
• If only WAIT_BUYER_PAY is returned during the query, the CANCEL interface must be called to force the transaction to close. For more information about the cancel retry logic, see Handling errors.

Note

The following rule applies to all products.

Sometimes, the cashier might be 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 in status WAIT_BUYER_PAY, and the timeout period can be slightly longer than the one set at the cashier side.

Online Payment

trade_status is used to describe the status of an Online Payment transaction in the specific interfaces. Possible values are:

• WAIT_BUYER_PAY: The transaction is created and is waiting for the customer to pay.
• TRADE_FINISHED: The transaction is paid. This status persists even if partial refunds or full refunds occur, or when the refund period is expired.
• TRADE_CLOSED: The transaction is closed because of payment timeout.

The relationships between the transaction statuses are illustrated in the following figure:

Figure 2. Online Payment transaction status

Related interfaces

For Online Payment transactions, trade_status is returned by the following interfaces: