Skip to main content

Idempotency

Definition​

Idempotency ensures that repeated API requests do not cause unintended duplicate transactions.
It is a critical mechanism in payment processing to handle retries safely.

Why is Idempotency Important?​

Requests to the Payment API may be accidentally duplicated due to:

  • Network failures, causing a retry.
  • Timeouts, leading the merchant system to resend the same request.
  • User actions, such as clicking multiple times on a "Pay" button.

Without idempotency, these scenarios could result in duplicate payments or refunds.

Best Practices​

  • Use an idempotency key (x-idempotency-key) for all operations that modify transactions (e.g., capture, refund, void).
  • The idempotency key should be unique per operation and generated by your system (e.g., a UUID).
  • If a request fails due to a timeout, retry the same request with the same idempotency key instead of creating a new one.
  • Store idempotency keys for a reasonable duration to prevent duplicate processing in case of failures.

Example​

Using Idempotency in a Capture Request​

curl -X POST "https://api.purse-sandbox.com/v2/payments/{{payment-id}}/captures" \\ 
     -H "Authorization: Bearer <access-token>" \\ 
     -H "Content-Type: application/json" \\ 
     -H "x-idempotency-key: 123e4567-e89b-12d3-a456-426614174000" \\ 
     -d '{ 
           "amount": 5000 
         }'

Even if the request is sent multiple times, the API will ensure that the capture is executed only once.

What happens if the same idempotency key is reused?

If you retry a request with the same x-idempotency-key, and the operation was already processed, the API will return a 409 Conflict response.

This response includes the original payment_id and operation_id, allowing you to recover the status of the previous request:

{
    "type": "urn:eu.purse:write-conflict",
    "title": "Idempotency violation",
    "status": 409,
    "instance": "/v2/payments/558f47c6-fd88-4c28-aa2f-5d3d7a44709f/captures",
    "resource_id": "432ccde8-13e8-4c31-a900-a9c40546c12a"
}