メインコンテンツへスキップ
このページで

ネットワーク障害またはクライアントタイムアウトにより、ステート変更リクエストの結果が不確実な場合に、一貫性キーを使用します。 DEUNA は、キーを操作とリクエストボディに関連付け、保存された応答を再実行します。

再試行フロー#

01 · merchant
キーを 1 つだけ保存
ビジネス操作の前に、UUID v4 を生成し、保存します。
02 · DEUNA
処理または再実行
DEUNA は、同じキーとボディでリクエストを処理するか、保存された結果を再実行します。
03 · merchant
結果の一貫性
操作が完了したか、安全に再試行できるかを、応答と現在の注文ステートに基づいて判断します。

キーの生成、保存、および再試行タイミングは、商社に依存します。 DEUNA は、キー、操作、リクエストボディ、およびドキュメント化された保持期間内の保存された応答との関連性を管理します。

サポートされている操作#

送信 X-Idempotency-Key 以下の操作に対して:

操作メソッドとパス参照
注文の作成 · オプションフローPOST /merchants/orders注文を作成する
支払いを作成 · 購買 V2POST /v2/merchants/orders/purchase支払いを作成
承認された決済を実行POST /v2/merchants/orders/{order_token}/capture支払いをキャプチャ
承認を無効化POST /merchants/orders/{order_token}/void承認を無効化
支払いを返金POST /v2/merchants/orders/{order_token}/refund支払いを返金

すべての POST エンドポイントが一貫性をサポートしているとは限りません。 上記の操作リストを使用するか、エンドポイントの参照に一貫性に関する情報が含まれているかどうかを確認してください。 X-Idempotency-Key header.

キーを生成して保存#

各固有のビジネス操作に対して、Node.js で 1 つの UUID v4 を生成します。 DEUNA に呼び出す前に、独自の操作レコードに保存します。

Node.js でキーを生成JavaScript
const idempotencyKey = crypto.randomUUID();

以下のルールに従ってください:

  • 同じ操作の再試行時に、同じキーのみを使用します。
  • すべての再試行で、正確なリクエストボディを送信します。 DEUNA はボディのハッシュを比較するため、異なる形式でシリアライズされた、意味的に同等のボディは拒否されます。
  • 新しい支払い、キャプチャ、キャンセル、払い戻し、または注文作成の試行に対して、新しいキーを生成します。
  • リクエストデータを検証またはビジネスエラー後に修正した場合、新しいキーを生成します。
  • システムや環境間で衝突する可能性のある短いシーケンスからキーを生成しないでください。

キーは商社と操作にスコープされますが、統合は、グローバルに一意として扱い、別の操作に対して意図的に再利用しないでください。

リクエストを送信#

元のリクエストと、そのすべての再試行にキーを追加します。 この Purchase V2 の例では、統合がすでに作成した注文トークンを使用しています:

curl --request POST \
  --url https://api.sandbox.deuna.io/v2/merchants/orders/purchase \
  --header "X-Api-Key: YOUR_PRIVATE_API_KEY" \
  --header "X-Idempotency-Key: 9f510c4a-0f7d-4c31-94c5-590b85e4d231" \
  --header "Content-Type: application/json" \
  --data '{
    "order_token": "ORDER_TOKEN",
    "payer_info": {
      "email": "buyer@example.com",
      "external_user_id": "customer_1042"
    },
    "payment_source": {
      "method_type": "credit_card",
      "payment_method": "PAYMENT_METHOD_TOKEN"
    }
  }'

応答に X-Idempotency-Replay: trueが含まれている場合、DEUNA は、同じキーとボディを持つ以前のリクエストの保存された結果を返します。 応答のステータスコードとペイロードを、元の応答と同じように処理します。

保持期間を理解#

キーとボディの関連性は、DEUNA がキーを受信したときに開始されます。 保存された結果の再実行ウィンドウは、DEUNA が結果を保存したときに開始され、その結果によって制御されます。

元の結果再実行の動作
成功した応答DEUNA は、操作が完了した後に、デフォルトで 24時間 を保存します。 同じキーとボディで、その期間中に再試行すると、保存されたステータスコード、ヘッダー、およびペイロードが返されます。
4xx または 5xx 応答DEUNA は、約 2 秒 直ちに重複を処理するために。キーと元のリクエストボディ間の関連性は、24 時間の有効期間全体に維持されます。
リクエストは現在実行中競合するリクエストは、最初の結果を待機します。最初のリクエストがまだ実行中の場合、DEUNA は HTTP 409 ~ IS-4409.

正常な応答の保持期間が終了した後、同じキーは新しい操作として扱われます。この動作に依存しないでください。新しいビジネス試行ごとに、古いキーが期限切れになった場合でも、新しいキーを作成してください。

エラー応答の場合、修正されたリクエストデータでキーを再利用しないでください。元のボディとの関連性が維持されているため、変更されたボディが返されます。 IS-4401 保持期間が終了するまで。リクエストを修正し、新しいキーを使用して新しい操作として送信してください。

リトライと競合の処理#

状況DEUNA が返す情報統合側で実行すべき処理
正常に完了したリクエスト後の、同じキーとボディ保存されたレスポンス X-Idempotency-Replay: trueレスポンスを受け入れ、最終的な状態でない場合に現在の注文の状態を再調整します。
同じキーで異なるボディを使用HTTP 400、コード IS-4401同じ組み合わせでの再試行は行わないでください。変更されたボディが修正または新しい操作を表す場合にのみ、新しいキーを使用してください。
最初のリクエストが実行中の間に重複リクエストが到着HTTP 409、コード IS-4409、待機が完了したときバックオフし、同じキーを使用して正確なリクエストを再試行します。新しい試行を開始する前に、元の注文を再調整してください。
レート制限を超過HTTP 429, 含まれる可能性のあるコード IS-4429名誉 Retry-After 存在する場合、同じリクエストボディとキーで再試行します。
クライアントのタイムアウトまたは接続の喪失クライアントは、処理が継続中でも応答を受け取らない場合があります。キーとボディを保持し、注文を照合し、ドキュメント化されたタイムアウト手順に従ってのみ再試行してください。
再試行できない検証またはビジネスエラーA 4xx 応答リクエストを修正し、新しいキーを使用してください。 変更されたボディを古いキーで再試行しないでください。

制限付きの指数関数的バックオフとジャイターを使用してください。同じビジネス操作に対して複数の並行リトライを送信しないでください。

参照 APIのエラー レスポンスコードモデルと クライアントタイムアウト および、整合性プロセスのために。

サンドボックス環境での動作を確認#

  1. 有効なサポートされているリクエストを送信し、 https://api.sandbox.deuna.io 新しい UUID v4 キーを使用してください。
  2. ステータスコード、レスポンスヘッダー、およびペイロードを保存してください。
  3. 同じキーとボディを使用して、正確なリクエストを再度送信してください。
  4. 2番目のレスポンスが同じ結果を含んでいることを確認してください。 X-Idempotency-Replay: true.
  5. 別のネガティブテストでは、ボディを変更し、キーは保持して、DEUNAがHTTPを返すことを確認してください。 400 ~ IS-4401.

テスト用のキーを別のサンドボックス操作には再利用しないでください。

統合を続行#