OpenAPIタイプ ポイント 処理フロー
決済処理シーケンス
ポイント認可のタイミングと対応機能はポイント事業者によって異なるため、処理シーケンスは3パターンに分かれます。
| パターン | ポイント事業者 | 特徴 |
|---|---|---|
| 事前認可型 | Vポイント | 事前に1回だけ認可すれば、以降の取引で再利用できます |
| 都度認可型 | Pontaポイント | ポイント利用のたびに認可が必要です（ポイント付与・残高照会は事前に1回で再利用できます） |
| 付与のみ | PayPayポイント | 事前に1回だけ認可。ポイント利用（代金への充当）は非対応です |
ポイント認可では、お客様のブラウザがポイント事業者の画面へ遷移し、認可完了後にポイントGWおよび当サービスを経由して merchant.callbackUrl へ復帰します。
復帰は加盟店様サーバーへの直接通知（サーバー間通信）ではなく、ブラウザのリダイレクトで行われます。
- 事前認可型（Vポイント）
- 都度認可型（Pontaポイント）
- 付与のみ（PayPayポイント）
事前に取得した認可を再利用し、代金の一部をポイントで充当して残額を決済し、売上確定後にポイントを付与する流れです。
いつ・どのAPIを呼ぶか
| # | タイミング | API | 目的 |
|---|---|---|---|
| 1 | 事前（1回のみ） | ポイント認可開始（/point/start）API | 認可開始（ポイント事業者の画面へリダイレクト） |
| 2 | 認可コールバック受信後 | ポイント認可結果確認（/point/memberinquiry）API | 認可結果と pointAccountReference を確認 |
| 3 | 認可完了直後 / 購買の実施前 | ポイント残高照会（/point/balance）API | 保有ポイント数を取得してお客様に表示 |
| 4 | お客様が利用ポイント数を入力した後 | ポイント利用（/point/use）API | ポイントを代金に充当 |
| 5 | ポイント充当後 | 支払い（/credit/charge）API 等 | 残額をカード払い/Pay払いで決済 |
| 6 | 決済成功・売上確定後 | ポイント付与（/point/grant）API | 購入特典ポイントを付与（非同期） |
| 7 | 付与後の確認 | ポイント取引照会（/point/inquiry）API | 付与確定を確認（Webhook通知の補完） |
| 8 | 決済失敗時 | ポイント利用取消（/point/cancel）API | ポイント利用を取消してロールバック |
手順3の残高照会は、初回の認可完了直後と購買の実施前の両方で必ず実施してください。
また、ポイント利用にあたってお客様のパスワード認証を周期的に再取得する必要があります。詳細は事業者別の仕様差異を参照ください。
Pontaポイントでは、ポイント利用のたびに認可（おまとめ認証）が必要です。
残高照会の後、ポイント利用の前に認可フローを実行し、払い出された pointAccountReference が保持している値と一致することを確認してから利用に進みます。
いつ・どのAPIを呼ぶか
| # | タイミング | API | 目的 |
|---|---|---|---|
| 1 | 会員登録時 | ポイント認可開始（/point/start）API | 認可開始（ポイント事業者の画面へリダイレクト） |
| 2 | 認可コールバック受信後 | ポイント認可結果確認（/point/memberinquiry）API | pointAccountReference を取得して保持 |
| 3 | 支払い画面表示時 | ポイント残高照会（/point/balance）API | 保有ポイント数を取得してお客様に表示 |
| 4 | 残高照会の後、ポイント利用の前 | ポイント認可開始（/point/start）API | 都度認可（おまとめ認証をやり直す） |
| 5 | 都度認可のコールバック受信後 | ポイント認可結果確認（/point/memberinquiry）API | 払い出された pointAccountReference を取得 |
| 6 | 手順5の直後 | — | 手順2で保持した値と一致するかを加盟店様側で確認（一致しない場合は以降を実行しない） |
| 7 | 一致確認後 | ポイント利用（/point/use）API | ポイントを代金に充当 |
| 8 | ポイント充当後 | 支払い（/credit/charge）API 等 | 残額をカード払い/Pay払いで決済 |
| 9 | 決済成功・売上確定後 | ポイント付与（/point/grant）API | 購入特典ポイントを付与（非同期） |
| 10 | 決済失敗時 | ポイント利用取消（/point/cancel）API | ポイント利用を取消してロールバック |
残高照会の後、手順4〜6の都度認可と一致確認を省略して、保持している pointAccountReference でポイント利用（/point/use）APIを呼び出すこと。
他のポイント事業者ではこの実装で動作しますが、Pontaポイントでは認められません。
ポイント付与のみを行う場合、都度認可は不要です。 保持している pointAccountReference をそのまま指定できます。
ポイント残高照会も都度認可を必要としません。
PayPayポイントはポイント利用（代金への充当）に非対応のため、ポイント付与のみを行う流れです。
いつ・どのAPIを呼ぶか
| # | タイミング | API | 目的 |
|---|---|---|---|
| 1 | 事前（1回のみ） | ポイント認可開始（/point/start）API | 認可開始（ポイント事業者の画面へリダイレクト） |
| 2 | 認可コールバック受信後 | ポイント認可結果確認（/point/memberinquiry）API | 認可結果と pointAccountReference を確認 |
| 3 | 決済成功・売上確定後 | ポイント付与（/point/grant）API | 購入特典ポイントを付与（非同期） |
| 4 | 付与後の確認 | ポイント取引照会（/point/inquiry）API | 付与確定を確認（Webhook通知の補完） |
PayPayポイントはポイント残高照会（/point/balance）APIにも非対応です。
orderDescription に設定した値はPayPayアプリのポイント履歴に表示されます。詳細は事業者別の仕様差異を参照ください。
ポイント利用は決済より先に行ってください
ポイント利用とカード払い/Pay払いの順序を入れ替えないでください。
決済が失敗した場合にポイント利用取消（/point/cancel）APIでポイント利用を取消してロールバックできる構成にするためです。