Idempotency - Waffo Documentation

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

Error Handling Choosing an integration approach

⌘I

​Idempotency keys

​Rules

​Pattern

​Common mistakes

Idempotency keys

Rules

Pattern

Common mistakes