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

Best Practice

Keep transactions in final status

When you are dealing with a transaction, you might be in one of the following transaction status:

Best Practice

  • WAIT_BUYER_PAY: the system is waiting for the buyer to pay.
  • TRADE_FINISHED: the trade succeeds and supports for refunds.
  • TRADE_CLOSED: the trade is unpaid or timed out.

Your system can avoid many potential problems when your transaction is in the final status, which is TRADE_FINISHED or TRADE_CLOSED. To keep transactions in the final status, you can take the following actions:

  1. Set the time-out value. For example, you can set 3 minutes as the time-out value.
  2. Get the payment result with the page redirection caused by the synchronous notification.
  3. Confirm the payment result with the asynchronous notification.
  4. If no payment result or asynchronous notification is returned, the transaction status must be THE SYSTEM IS CONFIRMING THE PAYMENT RESULT or THE PAYMENT IS WAITING TO BE PAID.
  5. Every time the user enters the order system, the query API will be called to confirm the payment result.
  6. For all the unpaid transactions over 3 minutes, set the transaction status as TRADE_CLOSED.

Idempotence

Idempotence is the property of Alipay sending back only one unique result for the same requests that were sent multiple times. Alipay checks the idempotence to keep an accurate transaction or refund result for each request. To help Alipay checks the idempotence, you need to take the following actions:

  • For the same payment requests that were sent multiple times, provide the same out_trade_no for the same payment requests. Requests with the same out_trade_no are considered as the same transaction.
  • For the same refund requests that were sent multiple times, provide the same out_trade_no and partner_transaction_id for refund requests that were sent multiple times. Requests with the same out_trade_no and partner_transaction_id are considered as the same transaction.

Alipay checks the idempotence for payment and refund requests in the following ways:

  • For the payment requests with a same PID:

After receiving a payment request, Alipay checks the idempotence of out_trade_no (partner_transaction_id). Transactions with a same out_trade_no are considered as same transactions. Alipay then checks other information such as the buyer information and the transaction amount. If the information does not match with that in the Alipay system, errors will be returned. Otherwise, Alipay returns the real status of the transaction.

  • For the refund request with a same PID:

After receiving a refund request, Alipay checks the idempotence of out_trade_no (partner_transaction_id) and partner_refund_id. Refunds with a same out_trade_no AND partner_transaction_id are considered as same transactions. Alipay then checks information such as the amount of the refund. If this information does not match with that in the Alipay system, errors will be returned. Otherwise, Alipay returns the real status of the refund.

For more details about idempotency, see API idempotency.