冪等なリクエスト

当社APIでは冪等なリクエストを行うことができます。
冪等性は強力な安全性を提供するため、予期しない理由などで1つのリクエストが複数回実行されないようにし、重複決済を防ぐことができます。

利用可能なメソッド

冪等性リクエストは POST、PATCH リクエストでのみ利用可能です。
特にトランザクショントークン、課金、定期課金、返金などの作成や更新時は、常に冪等性リクエストを使用することを推奨します。

利用方法

上記、利用可能メソッドのリクエストヘッダに Idempotency-Key キーを指定することで利用可能です。
※任意の文字列を指定できますが、UUIDのようにランダムに生成された文字列を使用することを推奨します

※冪等性の保証は現在ベストエフォートで提供されており、冪等性のチェックができない状態が発生する可能性があります。
この場合リクエストが処理された後、レスポンスの Idempotency-Status ヘッダに error が入ります。

冪等性リクエストの仕組み

リクエストに冪等性キーが指定された場合、当社APIはまず、以前に同じキーのリクエストが処理されたかを確認します。

• 既に処理されていた場合：そのリクエストを再度処理せずに、API内部のキャッシュに保存されている過去のレスポンスを返却します。
• まだ処理されていなかった場合：通常どおりリクエストを処理し、将来冪等性リクエストが来る時に備え、レスポンスの内容を冪等性キーをキーとしてAPI内部のキャッシュに保存します。

※冪等性キーの有効期間は24時間です。同じ冪等性キーの2回目リクエストがこの期限を過ぎてしまった場合、APIはこれを1回目のリクエストとみなして実行してしまいます。

レスポンス

冪等性リクエストのレスポンスには、Idempotency-Status ヘッダが含まれます。(以下表参照)

値	説明
disabled	冪等性リクエストをサポートしていない
successfully_stored	このレスポンスは指定された冪等性キーとして保存され。※ 同じキーを使用した次回のリクエストは、この保存されたレスポンスが返される
retrieved_idempotent_response	リクエストは実際には処理されず、指定した冪等性キーとして保存されているレスポンスが返された
error	API内部のキャッシュからレスポンスの取得する時、もしくはキャッシュに処理結果を保存時に何らかのエラーが発生した為、冪等性のチェックができなかった リクエストされた処理は実行されている
conflicting_key	指定された冪等性キーが以前に異なるAPIやメソッドで使用されている

冪等性リクエストによる課金制限の変更

同一リカーリングトークンまたは同一カードに対して同一金額 ※ で連続して課金を行う場合、30秒以下の間隔で実行しようとすると、課金制限によってエラー「400 CHARGE_TOO_QUICK」が発生します。
※定期課金に関して、以下の場合のみ、違う金額でも課金制限が適用されます。

• 同一カードに対して、連続して定期課金を行う場合
• 同一リカーリングトークンに対して、連続して行う課金の種類が異なる場合（都度課金後、定期課金 / 定期課金後、都度課金）

課金制限は、冪等性キーの実装 かつ サポートデスクへの依頼によって、最短1秒に変更可能です。
同一消費者に対して連続で課金できる間隔を短縮したい場合は、サポートデスク（ips-support@univapay.com）へお問い合わせください。