Implementing error handling

Alipay returned error codes can be divided into the following types:

  • Business error codes:¬†
    Error code messages need to be created for such error codes so that the cashiers can easily understand the error. In addition, cashiers need to be trained to handle these errors or explain related problems to customers.
  • Timeout or system error:
    Mechanisms should be designed in the integration phase to handle this kind of errors. If such error  codes appear in production environments, partner's alarm mechanism should to be triggered, and investigation must be made to help fix the problems.

Timeout or system error (SYSTEM_ERROR)
Because HTTPS requests depend on network stabilities, timeout might occur to PAY, QUERY, CANCEL 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.

  • For the QUERY, CANCEL or REFUND interface:
    Retry with the same parameter until you get a result. If you retried more than the maximum times allowed, alarms will be triggered to notify the technical support team of the partner to check. If the retry results are always SYSTEM_ERROR, contact Alipay Technical Support for help.
  • For the PAY interface:
    a. Retry with the same parameter until you get a result. If you retried more than the maximum 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.
    b. If timeout or SYSTEM_ERROR returned, call the QUERY interface to obtain the status, if the QUERY process times out again, call the CANCEL interface to close the transaction.

The following table lists the differences of using method a and method b:

Alipay statusRetry PAY interfaceRetry QUERY interface
SYSTEM_ERRORSYSTEM_ERRORTRADE_NOT_EXIST
WAIT_BUERY_PAYUNKNOWWAIT_BUERY_PAY
TRADE_SUCCESSTRADE_SUCCESSTRADE_SUCCESS
TRADE_CLOSEDTRADE_CLOSEDTRADE_CLOSED