ポーリング
概要
ポーリングとは、対象のトランザクションに対してステータスの変化を検出するまで GET リクエストを行い、トランザクションのステータスが変化したタイミングで通知を受け取れる実装方法です。
当社APIのトランザクションは、作成直後に処理中（pending）のステータスになりますが、処理結果がクレジットカード会社などの決済事業者によって反映されていない状態のため、参考になる情報ではありません。
そのため、決済を行った後、消費者に対して決済の状態をなるべく早く反映させたい場合は、ポーリングの利用を推奨します。
ポーリングではなく、ウェブフックを利用してステータスを取得する場合は、こちらのページを参照してください。
ポーリング可能なリソース
以下4つのリソースに対して、1回のAPIリクエストでトランザクションのステータスを効率的にポーリングする手段を提供しています。
これらのリソースに GET リクエストを送信する時、リクエストURLに対してクエリパラメータで polling ： true と指定すると、対象のリソースが最終的な状態に遷移するまでAPIの内部でポーリングします。
例）課金の GET リクエスト
https://api.univapay.com/stores/{storeId}/charges/{chargeId}?polling=true
リソースごとの、最終的な状態を表すステータスは下記の通りです。
| リソース | 最終的な状態を表すステータス |
|---|---|
| 課金 | Canceled, Error, Failed, Successful |
| 返金 | Error, Failed, Successful |
| キャンセル | Error, Failed, Successful |
| 定期課金 | ‐ |
最初の状態が、課金：処理中（pending） / 定期課金：待機中（Unverified）の場合、何かしらステータスが変化したタイミングで「最終的な状態」とみなし、ポーリングは終了します。
注意点
ポーリング利用時は、以下の点に注意してください。
- ポーリング実行から3秒以内にステータスが変化した場合、更新されたレスポンスを返します。
ステータス変更がない場合は、状態が何であっても3秒後時点の状態を返します。 - GETリクエストのレスポンスが502,503,504のエラーだった場合は、一時的な通信環境の悪化が原因の可能性があるため、数秒後に再度リクエストを行うと、結果が成功（
Successful）になる場合があります。
そのため、これらのエラーが返却された場合、すぐに決済失敗と判断しないよう注意してください。 - 当社提供のパラメータを利用せず、加盟店さま側で独自にポーリング処理を実装する場合、APIの制限を受けないよう適切なエラー処理を行ったポーリングの仕組みを実装する必要があります。
そのため、当社の提供する手段を利用した実装を推奨します。
