Idempotency Guidelines

Your payment gateway adapter is linked to a PaymentGatewayProvider record. The Salesforce payments platform can detect when the same payment request is submitted more than once. For example, a user clicks Pay twice, or a client retries after a timeout. If your gateway can handle those retries without charging twice, set IdempotencySupported to Yes on the PaymentGatewayProvider record. For an example, see Set Up a Synchronous Payment Gateway Adapter.

When the payments platform detects a duplicate and the gateway provider supports idempotency, it still calls your adapter’s processRequest method and sets the request’s duplicate property to true. Check that property before you send a callout to the payment processor. You can also read idempotencyKey and include it in the outbound request so the processor can reject a later retry. These properties are available on capture requests and on other request types, such as authorization and refund.

This example shows the check for a capture request.

1global commercepayments.GatewayResponse processRequest(
2        commercepayments.PaymentGatewayContext gatewayContext) {
3    commercepayments.CaptureRequest request =
4        (commercepayments.CaptureRequest) gatewayContext.getPaymentRequest();
5
6    Boolean isDuplicate = request.duplicate;
7    String idempotencyKey = request.idempotencyKey;
8
9    if (isDuplicate) {
10        // Salesforce detected a retry of this capture. Do not send a new
11        // capture to the payment gateway.
12    } else {
13        // First request. Include idempotencyKey in the outbound call so
14        // the processor can reject a later retry of the same capture.
15    }
16}