Alipay+ DocsAlipay+ Docs

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 (Cashier Payment)

paymentRequestId

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