冪等性 - Waffo Documentation

冪等性とは、同じリクエストを複数回実行しても、1 回だけ実行した場合と同じ結果になることを保証する性質です。決済のシナリオでは、ネットワークタイムアウトによるリトライに起因する二重課金を防ぎます。

冪等キー

Waffo では paymentRequestId(決済)と subscriptionRequest(サブスクリプション)を冪等キーとして使用します。

ルール

最大長: 32 文字
新しいリクエストごとに一意の値を生成
リクエスト送信前にデータベースへ永続化すること
リトライ時は 元の冪等キーを再利用 し、新しいキーを生成しないこと

パターン

// 1. 32文字以内の一意な冪等キーを生成
const paymentRequestId = generateUniqueRequestId();

// 2. 永続化(リクエスト送信前に!)
await db.order.create({ paymentRequestId, status: 'PENDING' });

// 3. リクエスト送信
try {
  const response = await waffo.order().create({ paymentRequestId, ... });
} catch (e) {
  if (e instanceof WaffoUnknownStatusException) {
    // 4. ステータス不明: create を再試行せず、照会すること
    const inquiry = await waffo.order().inquiry({ paymentRequestId });
  }
}

よくある間違い