ポイント 概要
概要
ポイントは、お客様が保有するポイント事業者のポイントを、加盟店様のサービス上で 利用（代金への充当） および 付与 できる機能です。
お客様のポイント口座と加盟店様の会員を紐づける ポイント認可 を行うことで、以降は当サービスのAPIを通じてポイントの残高照会・利用・付与を行えます。
ポイントは OpenAPIタイプ でのみご利用いただけます。
リンクタイプ Plus、プロトコルタイプ／モジュールタイプでは提供していません。
対応ポイント事業者
| ポイント事業者 | pointType | 残高照会 | ポイント利用 | ポイント付与 |
|---|---|---|---|---|
| Pontaポイント | PONTA | ○ | ○ | ○ |
| Vポイント | VPOINT | ○ | ○ | ○ |
| PayPayポイント | PAYPAY | × | × | ○ |
事業者ごとの仕様差異（認可のタイミング、対応API、必須パラメーター、レスポンス項目、運用フロー）は事業者別の仕様差異にまとめています。
事業者に依らない制約と加盟店様側で実装が必要な事項は制約事項と運用ルールにまとめています。
実装前に必ず確認してください。
ポイントでできること
ポイント認可（会員連携）
お客様をポイント事業者の認証／同意画面へ誘導し、加盟店様の会員IDとポイント口座を紐づけます。
ポイントの残高照会・利用・付与は、すべて認可済みの会員に対してのみ実行できます。
認可が必要なタイミングは事業者と操作によって異なります。
- Vポイント / PayPayポイント：事前に1回だけ認可すれば、以降の取引で再利用できます
- Pontaポイント：ポイント利用は都度、認可が必要です。 残高照会とポイント付与は、事前に1回だけ認可すれば以降の取引で再利用できます
ポイント利用（代金への充当）
お客様の保有ポイントを商品代金に充当します。
ポイントで充当しきれない残額は、クレジットカードやPay払いなど他の決済手段と組み合わせてお支払いいただけます。
利用したポイントは、減額（利用ポイント変更）または全額取消ができます。
ただし購買金額の減額が発生した場合は、利用ポイント数は変更せず、ポイント以外の決済手段の金額から先に減額してください。
ポイント利用を行った取引では、付与ポイントが 0 の場合でもポイント付与の依頼が必須です。
ポイント付与
購入特典などのポイントをお客様に付与します。
付与は 非同期処理 です。リクエスト受付時点で 202 Accepted を返し、処理結果はWebhook通知またはポイント取引照会で確認します。
ポイント付与は、原則としてキャンセルを行わない運用を前提としています。
お客様の購入・配送が確定したタイミング（商品キャンセル等が発生しないタイミング）以降で付与を行うよう運用してください。
やむを得ずポイント付与を取り消す場合は、全額取消のみ可能です（部分取消はできません）。
また、全額取消をリクエストしても、お客様のポイント残高が不足している場合は残高分しか取り消せないことがあります。
詳細は制約事項と運用ルールをご確認ください。
残高照会
お客様の保有ポイント数と、ポイントを利用できる状態かどうかを取得します。
ポイント利用画面で利用可能ポイント数を表示する場合などに使用します。
PayPayポイントは残高照会に対応していません。
取引ステータス
ポイントの取引状態は、レスポンスの orderReference.status で確認できます。
| 区分 | ステータス | 説明 |
|---|---|---|
| 共通 | UNPROCESSED | 未処理／結果不明。ポイント取引照会APIで確定状態を確認してください |
| 利用 | USE | 利用済み |
| 利用 | USECANCEL | 利用取消済み |
| 付与 | REQSUCCESS | 付与受付済み（結果通知待ち） |
| 付与 | GRANT | 付与確定 |
| 付与 | GRANTFAIL | 付与失敗確定（取消は不要） |
| 付与 | REQCANCEL | 付与取消受付済み（結果通知待ち） |
| 付与 | GRANTCANCEL | 付与取消確定 |
| 認可 | REQSUCCESS | 認可依頼受付済み（お客様の認可操作待ち） |
| 認可 | REGISTER | 認可済み（ポイント利用・付与が可能） |
| 認可 | REGISTERFAIL | 認可失敗 |