> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Use idempotency keys to prevent duplicate charges and ensure payment security.

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

```typescript theme={null}
// 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

Incorrect approach

<ul />

Correct approach

<ul />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.