Idempotency

Idempotency keys prevent duplicate transactions. Every payment and payout request must include a unique idempotency_key.

Generating Keys

// Use order ID and timestamp
const idempotencyKey = `order_${orderId}_${Date.now()}`;
// Example: "order_12345_1705312800000"

// Or use UUID
const { v4: uuidv4 } = require('uuid');
const idempotencyKey = uuidv4();
// Example: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"

Behavior

• Same key, same request: Returns cached response (no duplicate charge)
• Same key, different request: Returns 409 Conflict
• Keys expire: 24 hours

Best Practices

1. Generate a unique key per business transaction
2. Store the key with your order records
3. Never reuse keys across different amounts or recipients
4. Use consistent formatting (e.g., order_12345_payment)

Recommended Patterns

order_{order_id}_{event}
payout_{user_id}_{timestamp}
checkout_{session_id}