Introduction

In web services, idempotent requests ensure that sending an identical request multiple times has the same effect as sending it once. This is especially important for submitting payment requests: Sending a CreateHostedCheckout/CreatePayment for a specific order accidentally multiple times will still charge your customers only once.

Implement Idempotent Requests

To ensure a request is processed only once, you must include a unique identifier in the HTTP header of your request. This identifier is referred to as the key which:

• Must be unique to each transaction to ensure the request is processed once.
• Has a maximum length of 40 characters.
• Should be ASCII compliant and not support UTF-8.

Possible outcomes of idempotent requests

• For completed requests: Our server will respond with the same outcome as the original request, even with different payloads. Updates related to the operation, such as payment status, may still occur.
• For requests in progress: A response with an HTTP status code of 409 (Conflict) will indicate that the request is currently being processed. Make sure to handle this scenario in your client application.

Response headers for subsequent requests 

For any follow-up requests made with the same idempotency key, our response includes an additional header, X-GCS-Idempotence-Request-Timestamp. This header indicates the timestamp of the initial request in milliseconds since January 1st, 1970 00:00:00 UTC. 

Supported Methods

The following API methods support idempotent requests:

• CreatePayment
• CancelPayment
• RefundPayment
• CapturePayment
• CompletePayment
• CreatePayout
• SubsequentPayment