Error handling

This section provides information about exceptional cases and error codes.

Exceptional cases

You might encounter problems when you integrate with Alipay+. This section presents typical exceptional cases that might be encountered and corresponding resolutions.

Payment timeout

When the payment timeout occurs, the payment status returned from Alipay+ and Mobile Payment Provider (MPP) might be inconsistent. For example, the payment does not reach a final status at Alipay+ side but MPP returns the result status of S or F.

Possible reasons:

Network error. Alipay+ sends the payment request but does not receive the response from MPP. In this case, whether MPP receives the request or not is uncertain.
Processing timeout. The MPP internal processing for the payment times out. In this case, MPP receives the request but Alipay+ does not receive the response.
The user does not complete the payment timely in the Cashier Payment scenario, which results in the payment timeout.

Actions:

To avoid the inconsistent payment status caused by the payment timeout, follow the steps below:

MPP notifies the payment result to Alipay+ when the payment reaches the final status of success or failure. Alipay+ pushes the payment to the final status after receiving the notification.
Alipay+ calls the inquiryPayment interface to query the payment status to MPP and proceeds with the payment according to the inquiry result.
Alipay+ sets the maximum payment processing time limitation by specifying the paymentExpiryTime field in the payment request message to MPP. If the payment processing cannot be completed in the specified time limit, MPP closes the transaction after the time limit. If paymentExpiryTime is not specified in the payment request message, the default time limits for User-presented Mode Payment is 1 minute at most. After the transaction is closed, MPP notifies the payment result status of F to Alipay+.
If the previous three steps do not work out, Alipay+ closes the transaction and requests to cancel the transaction to MPP. When MPP receives the cancellation request from Alipay+, cancel the transaction unconditionally. See Cancel the transaction for details.

Inconsistent payment results

Inconsistent payment results might be caused by the following reasons and MPP can take actions accordingly.

Possible reasons:

Payment timeout. See Payment timeout for details.
Inconsistent notifications. MPP notifies different results for the same payment.

Actions:

For the inconsistent payment results caused by payment timeout, see Payment timeout for detailed actions.
If MPP notifies different results for the same payment to Alipay+, Alipay+ processes the first one notification request. If the payment result in the second notification request is different with that in the first one, Alipay+ returns the corresponding error code to MPP. MPP deals with the error code manually.
If the payment status in the Alipay+ system is inconsistent with that in the MPP system, the payment status in the clearing reports and settlement report provided by Alipay+ prevails. MPP deals with the inconsistency according to the reports. If any dispute exists, submit the application to Alipay+.

Failed refund

A failed refund might be caused by the following reasons and MPP can take actions accordingly.

Possible reasons:

Network error. Alipay+ sends the payment request but does not receive the response from MPP. In this case, whether MPP receives the request or not is uncertain.
System error. The following two cases might occur:

The MPP fails to process the refund request for internal system problems and Alipay+ receives the error code of SYSTEM_ERROR.
MPP processes the refund request successfully but Alipay+ fails to process the refund request for internal system problems.

Business error. The refund cannot be processed because of some business errors. For example, the user account is frozen.

Actions:

For the failed refunds caused by network error and system error, Alipay+ can retry with the same refundRequestId. MPP must process the refund request properly.
If the refund status in the Alipay+ system is inconsistent with that in the MPP system, Alipay+ presents this refund in the clearing reports and the settlement report generated for MPP. MPP deals with the refund and makes adjustments manually.

Failed cancellation

A failed cancellation might be caused by the following reasons and MPP can take actions accordingly.

Possible reasons:

Network error. Alipay+ sends the cancellation request but does not receive the response from MPP. In this case, whether MPP receives the request or not is uncertain.
System error. The following two cases might occur:

The MPP fails to process the cancellation request for internal system problems and Alipay+ receives the error code of SYSTEM_ERROR.
MPP processes the cancellation request successfully but Alipay+ fails to process the cancellation request for internal system problems.

Business error. MPP receives the cancellation request from Alipay+. However, the request processing is failed because of some business problems and MPP returns the detailed error code to Alipay+.

Actions:

For the failed cancellations caused by network error and system error, Alipay+ can retry with the same paymentRequestId. MPP must process the cancellation request properly.
For the failed cancellations caused by business problems, Alipay+ contacts with MPP for further actions.

Failed notification

MPP must integrate the notifyPayment interface to notify the payment status to Alipay+ when the payment reaches the final status of success or failure.

Possible reasons:

Network error. MPP sends the notification request but does not receive the response from Alipay+. In this case, whether Alipay+ receives the request or not is uncertain.
System error. Alipay+ receives the notification request sent by MPP but fails to process the request because of internal system problems. MPP receives the error code of SYSTEM_ERROR from Alipay+.
Business error. MPP sends the notification request to Alipay+. However, the request processing is failed because the payment is closed by Alipay+ already.

Actions:

For the failed notifications caused by network error and system error, MPP retries with the same paymentRequestId 15 times. MPP must retry for one time or twice within 5 seconds. If the payment status notification still fails after the two retries, MPP retries with an incremental retry interval from the third time, such as an interval of 30 seconds, 1 minutes, and 2 minutes.
For the failed notifications caused by business problems, MPP takes actions according to the returned error code.

Error codes

Learn more about common error codes and how to resolve them.

resultCode	resultStatus	resultMessage	Remark
KEY_NOT_FOUND	F	The key is not found.	Indicates that the server end cannot find a valid key against the client ID in the request. The Client ID exists but the RSA key is not configured.
INVALID_CLIENT	F	The client is invalid.	The Client ID does not exist or is invalid in the MPP system.
INVALID_CONTRACT	F	The contract is invalid.	The product contract is invalid. This result code is optional for MPP.
INVALID_TOKEN	F	The access token is invalid.	The possible reason might be incorrect token format, expired token, and so on.
INVALID_CODE	F	The code is invalid.	The payment code is invalid.
EXPIRED_CODE	F	The code is expired.	The payment code is expired.
PAYMENT_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the limit.	The payment amount in the request exceeds the MPP limit for a single payment transaction.
USER_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the user payment limit.	Plus the amount in the payment request, the accumulated payment amount within one period exceeds the MPP limit.
PAYMENT_COUNT_EXCEED_LIMIT	F	The number of payments exceeds the limit.	The result code is returned when the number of payments exceeds the limit set by MPP.
REPEAT_REQ_INCONSISTENT	F	Repeated requests are inconsistent.	The information in multiple requests with the same request ID is inconsistent.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	The result code is returned when the request exceeds the traffic limit of a specific API set by MPP.
PROCESS_FAIL	F	A general business failure occurred. Don't retry.	MPP can specify the detailed failure reasons in resultMessage for the more efficient troubleshooting.
UNKNOWN_EXCEPTION	U	An API calling is failed, which is caused by unknown reasons.	MPP can specify the detailed failure reasons in resultMessage for the more efficient troubleshooting.

Table 1. Error codes

Note:

If you have any questions about the result code, contact connect_support@service.alipay.com for help.