Idempotency

An API call is idempotent if the action is performed only once no matter how many times the API call is retried.

Idempotency helps to avoid unwanted duplication in case of failures and retries. For example, idempotency can guarantee that the payment is charged only once if the same API payment call is retried multiple times in the case of a timeout error.

In Alipay+, API idempotency is enabled by an idempotency field. Idempotency fields stay unique without a time limit.

Idempotency fields

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

Direction: ACQP > Alipay+

The following table lists the idempotency fields for APIs that are used by the Acquiring Service Provider (ACQP) to call Alipay+:

Interface	Field
pay (User-presented Mode Payment)	paymentRequestId
pay (Merchant-presented Mode Payment -Entry Code)
pay (Merchant-presented Mode Payment - Order Code)
pay (Cashier Payment)
pay (Auto Debit)
refund	refundRequestId
cancelPayment	paymentRequestId
prepare	authClientId and referenceAgreementId Note: authClientId and referenceAgreementId are jointly used for idempotency control.
cancelToken	accessToken
registration	registrationRequestId
declare	customsDeclarationRequestId
responseRetrieval	disputeRequestId
responseEscalation	disputeRequestId

Direction: Alipay+ > ACQP

For APIs that are used by Alipay+ to call the ACQP, the ACQP decides the idempotency fields. The following table lists the ones that are recommended by Alipay+:

Interface	Field
userInitiatedPay	codeValue
initiateRetrieval	disputeRequestId
initiateEscalation	disputeRequestId