Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

      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:

      trade status - 副本.png

      Figure 1. In-store Payment transaction status


      #Related interfaces

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

      Interface

      Method

      alipay.acquire.overseas.spot.pay

      Asynchronous notification

      alipay.acquire.create

      Asynchronous notification

      alipay.acquire.precreate (for third-party QR code payment) 

      Asynchronous notification

      alipay.acquire.precreate (for transaction QR code payment)

      Asynchronous notification

      alipay.commerce.qrcode.create

      Asynchronous notification

      alipay.acquire.overseas.query

      Synchronous response


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

      Interface

      Method

      alipay.trade.pay

      Asynchronous notification

      alipay.trade.query

      Synchronous response


      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:

      1.png

      Figure 2. Online Payment transaction status


      #Related interfaces

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

      Interface

      Method

      create_forex_trade

      Synchronous response and asynchronous notification

      create_forex_trade_wap

      Synchronous response and asynchronous notification

      mobile.securitypay.pay

      asynchronous notification

      single_trade_query

      Synchronous response