An API call is idempotent if the API call has the same result no matter how many times the API call is applied. The Alipay API supports idempotency, allowing you to retry a request multiple times while only performing the action once. The idempotency helps avoid unwanted duplication in case of failures and retries. For example, idempotency can guarantee that the payment will be charged only once if the same API payment call is retried multiple times in the case of a timeout error.

Idempotency fields for APIs

Alipay checks the idempotence for payment, refund, and other requests with the idempotency fields. Requests with same values for idempotency fields need to be processed idempotently. This section provides details about idempotency fields and idempotent processing rules for the payment, refund, code generation, secondary merchant registration, and declaration requests.

Payment

Online payment:

Idempotent processing rules:

If a transaction is created and the status of this transaction is not TRADE_NOT_EXIST, the idempotence control is triggered.

When another request from the same Alipay account with the same value of out_trade_no is received, Alipay processes the request with the following actions:

1. Alipay checks consistency of the two requests with the same values for idempotency fields. If inconsistency exists, an error of CONTEXT_INCONSISTENT is returned to the merchant. Otherwise, processing proceeds to the next step.
2. Alipay checks the status of the transaction. If the status is WAIT_BUYER_PAY, processing proceeds with the payment. Otherwise, an error about the transaction status, such as TRADE_HAS_SUCCESS, is returned to the merchant.

In-store payment:

Idempotent processing rules:

If a transaction is created, the idempotence control is triggered.

When another request from the same Alipay account with the same value of partner_trans_id is received, Alipay processes the request with the following actions:

1. Alipay checks consistency of the two requests with the same values for idempotency fields. If inconsistency exists, an error of CONTEXT_INCONSISTENT is returned to the merchant. Otherwise, processing proceeds to the next step.
2. Alipay checks the status of the transaction:

• If the status is WAIT_BUYER_PAY, Alipay proceeds with the payment again. If the payment process failed due to some reason, Alipay returns PULL_MOBILE_CASHIER_FAIL to the merchant.
• If the status is TRADE_SUCCESS, Alipay returns the payment result of the original payment request.
• If the status is TRADE_CLOSED or TRADE_FINISHED, Alipay returns an error code, such as TRADE_HAS_CLOSE, to the merchant. 

Refund

Idempotent processing rules:

If a refund request is created, the idempotence control is triggered.

When another request from the same Alipay account with the same value of out_return_no or partner_refund_id is received, Alipay checks consistency of the two requests with the same values for idempotency fields. If inconsistency exists, an error of REPEATED_REFUNDMENT_REQUEST or DISCORDANT_REPEAT_REQUEST is returned to the merchant. Otherwise, Alipay returns the refund result of the original refund request for the latest request.

Code generation

Transaction QR code generation：

Idempotent processing rules:

If a transaction is created, and the status of this transaction is not TRADE_NOT_EXIST, the idempotence control is triggered.

When another request from the same Alipay account with the same value of out_trade_no is received, Alipay returns a transaction QR code for the request. If the two requests with the same values for idempotency fields are inconsistent, an error is returned when the transaction QR code is scanned. Otherwise, Alipay proceeds with the original transaction again.

Merchant QR code generation：

Idempotent processing rules:

If a request is created, the idempotence control is triggered.

When another request from the same Alipay account with the same value of secondary_merchant_id and store_id is received, Alipay checks consistency between the two requests with the same values for idempotency fields. If the value of secondary_merchant_industry, secondary_merchant_name, or store_name is not identical to that of the original request, an error of QRCODE_HAS_BEEN_EXIST is returned to the merchant. Otherwise, Alipay returns the merchant QR code to the merchant. 

Note: 

If you modify values of fields that are not secondary_merchant_industry, secondary_merchant_name, or store_name, Alipay returns the merchant QR code normally. However, the modified values of these fields will not be updated to the Alipay system.

Register secondary merchants

Idempotent processing rules:

If a registration request is created, the idempotence control is triggered.

When another request from the same Alipay account with the same value of secondary_merchant_id, or same values of secondary_merchant_id and store_id is received, Alipay processes the request with the following actions:

1. If the status of the registration request is UNDER_REVIEW, Alipay returns an error of DUPLICATE_REQUEST to the merchant. Otherwise, processing proceeds to the next step.
2. Alipay modifies the registration information of the secondary merchant according to the information in the latest request.

Declaration

Idempotent processing rules:

If a declaration request is created, the idempotence control is triggered.

When another request from the same Alipay account with the same value of out_request_no is received, Alipay modifies the declaration information according to the information in the latest request if the following conditions are satisfied:

• The latest request is created at least five minutes after the previous request was created.
• Values of all fields must be consistent between the two requests. Or, values of all fields are consistent except the following fields:

• merchant_customs_code
• merchant_customs_name
• customs_place
• amount
• sub_out_biz_no

• Declaration modifications are permitted by the target customs.
• If the declaration amount is changed, the newly calculated total declaration amount cannot exceed the total amount of the original transaction.

Alipay returns different responses to the merchant in the following ways:

• If conditions for the declaration information modification are satisfied, the declaration modification will be performed and Alipay returns the same result as that of the first successful customs declaration request. 

• If conditions for the declaration information modification are not satisfied:

• If the request with idempotency fields is consistent with the original request, Alipay returns that the request is processed idempotently.
• If the request with idempotency fields is inconsistent with the original request, Alipay returns an error code, such as CONTEXT_INCONSISTENT.