Skip to main content
Idempotency ensures that retrying the same request multiple times has the same effect as making it once. This is crucial for preventing duplicate payments, refunds, and other operations in unreliable network conditions.

​
Idempotency-Key Header

ToffeePay supports idempotency for mutation operations (POST requests) using the Idempotency-Key header: 
POST /v1/sessions
Authorization: Bearer <your_access_token>
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

...

​
How It Works

  1. First Request: ToffeePay processes the request and stores the result with the idempotency key
  2. Duplicate Requests: If the same idempotency key is used again within 24 hours, ToffeePay returns the cached result instead of processing again
  3. Different Parameters: If the same key is used with different request parameters, ToffeePay returns an error

​
Supported Operations

Idempotency is supported for these operations:

​
Best Practices

​
Generate Unique Keys

Use UUIDs or other collision-resistant identifiers: 
import { v4 as uuidv4 } from 'uuid';

const idempotencyKey = uuidv4(); // e.g., "550e8400-e29b-41d4-a716-446655440000"

​
Key Per Operation

Use a different idempotency key for each distinct operation: 
// Good: Different keys for different operations
const sessionKey = `session-${userId}-${itemId}-${Date.now()}`;
const refundKey = `refund-${paymentId}-${Date.now()}`;

// Bad: Reusing the same key across different operations
const key = "my-operation-key"; // Don't do this

​
Error Handling

​
Idempotency Conflicts

If you use the same idempotency key with different parameters: 
HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key already used with different parameters"
  }
}

​
Key Expiration

Idempotency keys expire after 24 hours. After expiration, the same key can be reused.

​
Webhook Idempotency

For webhook processing, use the webhook-id header to deduplicate events. See the Webhooks page for details.