API Idempotency

Use idempotency keys to safely retry requests without creating duplicate operations.

What is idempotency?

An idempotent operation produces the same result whether executed once or multiple times. Idempotency keys allow you to retry failed requests without risk of duplicate payments.

Using idempotency keys

Include an Idempotency-Key header with a unique value:

curl -X POST https://api.plexypay.com/v2/payments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: order_12345_payment" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "currency": "USD"}'

How it works

1. First request with key abc123 - Creates payment, returns result
2. Retry with same key abc123 - Returns cached result (no new payment)
3. Different key xyz789 - Creates new payment

Key requirements

Generating keys

Use UUIDs or combine meaningful identifiers:

// UUID
const key = crypto.randomUUID();
// 'f47ac10b-58cc-4372-a567-0e02b2c3d479'

// Meaningful identifier
const key = `order_${orderId}_payment_${Date.now()}`;
// 'order_12345_payment_1679529600000'

When to use

Use idempotency keys for:

• Payment creation
• Refund creation
• Transfer creation
• Any operation that shouldn't be duplicated

Error handling

If you retry with the same key but different parameters:

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_in_use",
    "message": "Keys for different request parameters must be unique."
  }
}

Best practices

1. Generate unique keys - Use UUIDs or meaningful combinations
2. Store keys - Save the key with your order for retry capability
3. Don't reuse keys - Each operation needs a unique key
4. Handle conflicts - If key conflict occurs, use a new key

Retry logic

Generate the idempotency key once before the first attempt, then reuse the same key on every retry:

IDEMPOTENCY_KEY="payment_${ORDER_ID}_$(date +%s%3N)"

curl -X POST https://api.plexypay.com/v2/payments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"amount\": 5000, \"currency\": \"USD\", \"payment_method\": \"pm_card_visa\"}"

On a 5xx response, wait and retry with the same Idempotency-Key value. The API returns the cached result instead of creating a duplicate.

See also

• Error Codes