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

Idempotency

The Alipay API supports idempotency, allowing to retry a request multiple times while only performing the action once. This helps avoid unwanted duplication in case of failures and retries.

If a transient error or timeout occurred in the previous request, the subsequent retry pushes the action to its completion if the action was not completed in the previous request. If the action is already completed, the action is to be performed only once and the same result is to be returned for the retry process. All Alipay payment-related APIs are idempotent. The following table shows the most commonly used APIs and their idempotency rules.

Idempotency fields

The following table lists the idempotency fields of APIs. For details of the idempotency field, see the specific API chapter.

Interface name

Idempotency Field

Rule

pay

paymentRequestId

Merchant uses the paymentRequestId field for idempotency control. For payment requests that are initiated with the same value of paymentRequestId and reach a final status (S or F), the same result is to be returned for the request.

Note: This API checks the consistency of some key request parameters such as paymentRequestId, paymentAmount, and paymentMethodId if applicable. If any of the key values is different from that of the previous request, the error REPEAT_REQ_INCONSISTENT is to be returned.

refund

refundRequestId

Merchant uses the refundRequestId field for idempotency control. For payment requests that are initiated with the same value of refundRequestId and reach a final status (S or F), the same result is to be returned for the request. 

Note: If the value of refundAmount is different from that of the previous request, the error REPEAT_REQ_INCONSISTENT is to be returned. 

capture

captureRequestID

Merchant uses the captureRequestID field for idempotency control. For capture requests that are initiated with the same value of captureRequestId and reach a final status (S or F), the same result is to be returned for the request. 

Note: If the value of captureAmount is different from that of the previous request, the error REPEAT_REQ_INCONSISTENT is to be returned. 

registration

registrationRequestId

Merchant uses the registrationRequestId field for idempotency control. For registration requests that are initiated with the same value of registrationRequestId and reach a final status (S or F), the same result is to be returned for the request.

initAuthentication

authenticationRequestId

Merchant uses the authenticationRequestId field for idempotency control. For initAuthentication requests that are initiated with the same value of authenticationRequestId and reach a final status (S or F), the same result is to be returned for the request. 

Table 1. Idempotency fields and corresponding processing rules