Idempotency Key

Idempotency keys help you safely retry requests without accidentally performing the same operation twice.

Overview

When you make a request that creates or modifies a payment, you must include an X-Idempotency-Key header. This key ensures that if you retry the same request, the API will return the original response instead of creating a duplicate operation.

Supported Endpoints

Idempotency keys are required on the following endpoints:

Payment Endpoints

Endpoint
Operation

POST /v1/payments

Create payment

POST /v1/payments/{id}/capture

Capture payment

POST /v1/payments/{id}/void

Void payment

POST /v1/payments/{id}/refund

Refund payment

Transaction Endpoints

Endpoint
Operation

POST /v1/transactions/{id}/capture

Capture transaction

POST /v1/transactions/{id}/void

Void transaction

POST /v1/transactions/{id}/refund

Refund transaction

Usage

Include the X-Idempotency-Key header in your request:

Key Format

  • Type: We recommend using UUIDs, but any unique string can be used

  • Max length: 255 characters

  • Uniqueness: Must be unique per merchant account

Best Practices

  • Generate unique keys - Use UUIDs or meaningful identifiers combining order ID and timestamp

  • Store keys - Keep track of keys for potential retries

  • Key expiration - Keys are valid for 24 hours

  • Scope - Keys are scoped to your merchant account

Example Key Generation

Response Behavior

Scenario
Response

New request

Processes normally, stores result

Retry with same key and parameters

Returns stored result

Same key, different parameters

409 Conflict error

Key expired (after 24h)

Processes as new request

Last updated