Skip to main content
Idempotency ensures that when the same request is executed multiple times, the result is the same as executing it only once. In payment scenarios, this prevents duplicate charges caused by retries triggered by network timeouts.

​
Idempotency keys

Waffo uses paymentRequestId (payments) and subscriptionRequest (subscriptions) as idempotency keys.

​
Rules

  • Maximum length: 32 characters
  • Generate a unique value for each new request
  • Must be persisted to the database before sending the request
  • When retrying, reuse the original idempotency key; do not generate a new one

​
Pattern

// 1. Generate a unique idempotency key, 32 characters or fewer
const paymentRequestId = generateUniqueRequestId();

// 2. Persist (before sending the request!)
await db.order.create({ paymentRequestId, status: 'PENDING' });

// 3. Send the request
try {
  const response = await waffo.order().create({ paymentRequestId, ... });
} catch (e) {
  if (e instanceof WaffoUnknownStatusException) {
    // 4. Unknown status: inquire, do not retry create
    const inquiry = await waffo.order().inquiry({ paymentRequestId });
  }
}

​
Common mistakes