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 parameter. Idempotency parameters stay unique without a time limit.

Idempotency parameters

The following tables list the idempotency parameters of APIs and key parameters that are checked for consistency in idempotency control. For detailed information, see the specific API chapter.

Direction: Alipay+ > MPP

For APIs that are used by Alipay+ to call the MPP, the MPP decides the idempotency parameters and key parameters that are checked for consistency. The following table lists the ones that are recommended by Alipay+:

Interface

Idempotency parameter

Key parameter to check consistency

pay

paymentRequestId

paymentAmount, payToAmount, surchargeInfo, paymentMethod, and paymentPromoInfo

refund

refundRequestId

refundAmount, refundFromAmount, refundPromoInfo, and surchargeInfo

cancelPayment

paymentRequestId

N/A

prepare

authClientId and referenceAgreementId

Note:

It is recommended that authClientId and referenceAgreementId are jointly used for idempotency control.

authClientName, referenceMerchantId, authRedirectUrl, and scopes

cancelToken

accessToken

N/A

responseRetrieval

disputeRequestId

N/A

responseEscalation

disputeRequestId

refundType and refundAmount

Direction: MPP > Alipay+

For APIs that are used by the MPP to call Alipay+, Alipay+ decides the idempotency parameters and key parameters that are checked for consistency. The following table lists the ones that are specified by Alipay+:

Interface

Idempotency parameter

Key parameter to check consistency

notifyPayment

paymentRequestId

paymentAmount, paymentResult, paymentId, payToAmount, customerId, and customsDeclarationAmount

userInitiatedPay

codeValue

customerId

initiateRetrieval

disputeRequestId

paymentRequestId

initiateEscalation

disputeRequestId

paymentRequestId