API 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.
API | Idempotency Field | Idempotent Processing Rule |
Payment | 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. |
Table 1. Idempotency fields and corresponding processing rules