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:

curl -X POST https://api.flintn.com/v1/payments \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Idempotency-Key: ord_12345_pay_1704067200" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "currency": "USD"}'

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

// Using UUID v4
const idempotencyKey = crypto.randomUUID();

// Or with a meaningful prefix
const idempotencyKey = `payment-${orderId}-${Date.now()}`;

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