Idempotency

2022-01-21 05:03

If a request timeout error occurs when you call an API, you might attempt to resend the request. In this case, you can configure the specified idempotency fields in the request to help avoid unwanted duplication in case of failures and retries.

An API call is idempotent if it has the same result no matter how many times the API call is applied. 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. You can retry the request via using the same idempotency field to guarantee that no more than one charge is created.

Idempotency fields

The following table lists the idempotency fields of specific OpenAPI.

API name	Idempotency field	Rule
/v1/payments/pay /v2/payments/pay	paymentRequestId	This field is used for the idempotence control. For the payment requests which are initiated with the same `paymentRequestId` and reach a final status (S or F), the native app must return the unique result.
/v1/payments/refund /v2/payments/refund	refundRequestId	This field is used for the idempotence control. For the refund requests which are initiated with the same `refundRequestId` and reach a final status (S or F), the native must return the unique result.
v2/miniprogram/message/send	requestId	This field is an API idempotency field. For the notifications which are sent with the same `requestId` and reach an S status, the native app must return the same `messageId`.
/v2/miniprogram/qrcode/create	appId, appQrCodePage, appQrCodePage, and appQrCodeParams	These four fields are idempotency fields when they are used at the same time. For the QR code generated with the same `appId`, `appQrCodePage`, `appQrCodePage`, and `appQrCodeParams` and reach an S status, the same QR code value and image will be returned.