AlipayHKAlipayHKDOCS

Best Practice

Keep transactions in final status

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.

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.


For more information about the transaction status, see Trade status.

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.