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

Implementing error handling

The Alipay returned error codes can be divided to the following types:

  • Timeout or system errors: Mechanisms should be designed in the integration phase to handle this kind of errors. If such errors appear in production environments, partner's alarm mechanism should to be triggered, and investigation must be made to help fix the problems.
  • Business errors: Business errors should be expressed in a way that the cashiers can easily understand. In addition, the cashiers should be trained to handle these errors or explain errors to customers.

Idempotence

Idempotence means that in response to the same requests that are sent multiple times, Alipay sends back only one unique result.

Alipay checks the idempotence for payments and refunds. See details as below:

  • Payments with a same PID
    Alipay checks the idempotence of out_trade_no. Transactions with a same out_trade_no are considered as same transactions. Alipay then checks information such as the buyer and amount of the transaction. If the information does not match with that in the Alipay system, errors will be returned. Otherwise, Alipay returns the real status of the payment transaction.
  • Refunds with a same PID
    Alipay checks the idempotence of out_trade_no and out_return_no. Refunds with a same out_trade_no and out_return_no 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.

Timeout or system error

Depending on network stabilities, timeout errors might occur on QUERY and REFUND interface requests. At the same time, Alipay might return SYSTEM_ERROR for internal system problems. In both cases, you can retry or query to get aligned with the final transaction status in Alipay.

  1. For QUERY and REFUND interface:
  2. Retry with the same parameter till get a result. If the retry exceeds the max times allowed, alarms will be triggered to notify the technical support team of the partner to check. Query and refund results can be confirmed by synchronous or asynchronous notifications. If the retry results are always SYSTEM_ERROR, contact Alipay Technical Support for help.
  3. For PAY (mobile.securitypay.pay) interface:
  4. Retry with the same parameter till get a result. If the retry exceeds the max times allowed, alarms will be triggered to notify the technical team of the partner to check. If the retry results are always SYSTEM_ERROR, contact Alipay Technical Support for help.