メインコンテンツまでスキップ
Markdownをコピー

ポイント 事業者別の仕様差異

ポイントのAPIは各ポイント事業者で共通ですが、認可のタイミング・対応API・必須パラメーター・返却項目が事業者ごとに異なります。
実装前に本ページの差異を確認してください。

認可のタイミング​

ポイント事業者ポイント利用ポイント付与 / 残高照会
Pontaポイント利用の都度 認可が必要です事前に1回 認可すれば以降も再利用できます
Vポイント事前に1回 認可すれば以降も再利用できます同左
PayPayポイントポイント利用非対応事前に1回 認可すれば以降も再利用できます

Pontaポイントでポイント利用を行う場合の具体的な呼び出し順序は運用フローの差異を参照ください。

対応API​

APIPontaポイントVポイントPayPayポイント
ポイント認可開始（/point/start）API○○○
ポイント認可結果確認（/point/memberinquiry）API○○○
ポイント残高照会（/point/balance）API○○×
ポイント利用（/point/use）API○○×
利用ポイント変更（/point/change）API○○×
ポイント利用取消（/point/cancel）API○○×
ポイント付与（/point/grant）API○○○
ポイント付与取消（/point/grantcancel）API○○○
ポイント取引照会（/point/inquiry）API○○○
備考

PayPayポイントは ポイント認可とポイント付与のみ に対応しています。ポイント利用（代金への充当）と残高照会はご利用いただけません。
利用ポイント変更は 1取引につき1回まで です（ポイント事業者共通）。

リクエストパラメーターの差異​

pointInformation.pointAccountReference（ポイントアカウント参照キー）​

API設定説明
ポイント利用（/point/use）API
ポイント付与（/point/grant）API
ポイント残高照会（/point/balance）API		全事業者で必須認可完了後にポイント認可結果確認（/point/memberinquiry）APIで取得した値を設定します

Pontaポイントでお客様が複数カードを保有している場合、同一 pointType で pointAccountReference の異なる認可が複数存在します。どのカードを操作対象にするかを加盟店様側で選択できるようにしてください。

pointInformation.transactionInformation.paymentOrderId（決済オーダーID）​

ポイント利用（/point/use）APIでは、ポイント事業者を問わず必須です。ポイント付与（/point/grant）APIでの設定は事業者ごとに異なります。

ポイント事業者ポイント付与での設定
Pontaポイント任意（購買取引に紐づかない付与では指定不要）
Vポイント任意（購買取引に紐づかない付与では指定不要）
PayPayポイント必須
PayPayポイントは購買取引に紐づかないポイント付与をお受けできません

PayPayポイントでは、キャンペーン付与などの購買取引に紐づかないポイント付与をお受けできません。
ポイント付与（/point/grant）APIでも、対応する決済取引のオーダーIDを paymentOrderId に必ず指定してください。

pointInformation.transactionInformation.channel（チャネル区分）​

すべてのポイント事業者で必須です。事業者による差異はありません。

現在指定できる値は 12（WEB）のみです。ポイント事業者を問わず 12 を指定してください。

値説明対象事業者
12WEB全事業者

grantInformation.points[]（ポイント付与明細）​

category に指定できる値は事業者ごとに異なります。

ポイント事業者指定できる category明細数
PontaポイントREGULAR / BONUS複数可（category は重複不可）
VポイントREGULAR / BONUS複数可（category は重複不可）
PayPayポイントREGULAR のみ1明細のみ

対応外の組み合わせを指定した場合は invalid_parameter が返ります。 同一 category の明細を複数含められない点は事業者共通です。詳細は制約事項と運用ルールを参照ください。

Vポイントで BONUS を利用する場合は、事前に当社営業担当と実施内容をすりあわせてください。

grantInformation.providerOptions（事業者固有オプション）​

パラメーター対応事業者説明
orderDescriptionPayPayポイントのみポイント付与時の取引説明文。他事業者では無視されます
orderDescription はお客様が閲覧する値です

設定した値は PayPayアプリのポイント履歴に表示されます。
お客様が自分の取引を判別できる内容を設定してください（例：ショップ名_商品名）。
社内管理用のコードのみを設定するなど、お客様が意味を判別できない内容は避けてください。

運用フローの差異​

ポイント事業者によって、APIの呼び出し順序や加盟店様側で実装いただく必要のある処理が異なります。

Pontaポイント：ポイント利用の直前に毎回「おまとめ認証」が必要です​

Pontaポイントで最も注意が必要な制約です

会員登録時に払い出された pointAccountReference を保持していても、その値をそのままポイント利用に使うことはできません。

ポイント利用のたびに認可フローを実行し、新たに払い出された pointAccountReference が保持している値と一致するかを加盟店様側で確認してから利用に進んでください。
一致の確認は加盟店様の責務です。

操作ごとに都度認証が必要かどうかは以下のとおりです。

操作ポイント利用直前の都度おまとめ認証指定する pointAccountReference
ポイント利用必要（毎回）都度認証で払い出され、保持している値と一致を確認したもの
ポイント付与 / 付与取消不要会員登録等で取得し保持しているもの
ポイント残高照会不要会員登録等で取得し保持しているもの

都度認証の結果に応じた加盟店様側の分岐は以下のとおりです。

都度認証で払い出された pointAccountReference加盟店様側の対応
保持している値と一致するポイント利用を続行します
一致しないポイント利用を行わないでください。 認証したお客様またはカードが、保持している pointAccountReference の対象と異なることを意味します
  • 認可フローでは、お客様がポイント事業者側にログイン済みであってもおまとめ認証は省略されません
  • ポイント付与のみを行う場合、都度認証は不要です。 会員登録等で取得した pointAccountReference をそのまま指定できます
  • 1つの認可に対して複数の pointAccountReference が払い出される場合があります（お客様が複数のカードを連携した場合）。この場合は操作対象のカードに応じた値を選んでください

API の呼び出し順序​

ポイント利用は、以下の順序で実行してください。

  1. ポイント残高照会（/point/balance）API — お客様に残高を表示します
  2. ポイント認可開始（/point/start）API から認可フローを実行し、ポイント認可結果確認（/point/memberinquiry）APIで pointAccountReference を取得します
  3. 取得した pointAccountReference が保持している値と一致することを確認します（一致しない場合は以降を実行しません）
  4. 利用ポイント数を確定します
  5. ポイント利用（/point/use）APIを実行します

シーケンス図はOpenAPIタイプ ポイント 処理フローを参照ください。

Vポイント：ポイント利用時の本人認証​

ポイント利用は会員連携（ポイント認可）が完了していることを前提とします。そのうえで必要な本人認証は、お客様がブラウザから利用するかアプリから利用するかで異なります。

利用経路本人認証の設計
ブラウザ加盟店様のサイトでお客様のパスワード認証を一定の周期で再取得してください
アプリ追加の認証設計は不要です。 アプリまたは端末での認証をもって本人認証済みとして扱います

ブラウザの場合の認証周期は、加盟店様が取り扱う商材によって異なります。

加盟店様のサービスパスワード認証の周期
物品を販売するサイト（注文者以外へ商品が届きうるサービス）24時間につき1回以上
権利・デジタルコンテンツを販売するサイト（コイン・動画・漫画・視聴権等、注文者本人が受け取るサービス）15日につき1回以上
  • 上表は最長の間隔です。前回のパスワード認証からこの間隔を超えている場合は、ポイント利用の前に再度パスワード認証を実施してください
  • 認証周期の管理は加盟店様の責務です

Vポイント：ポイント残高照会の呼び出しタイミング​

以下の2つのタイミングでは、必ずポイント残高照会（/point/balance）APIを実施する実装としてください。

タイミング内容
初回の認可完了後会員連携（ポイント認可）が完了した直後
購買の実施前ポイント利用を伴う購買を実行する前
  • 呼び出しの実施は加盟店様の責務です
  • 会員ページ等で保有ポイントを表示する場合（type に screen を指定する場合）、残高照会は1日1回までとしてください

レスポンス項目の差異​

ポイント残高照会（/point/balance）​

PayPayポイントは残高照会に対応していないため、対象はPontaポイントとVポイントです。

項目説明返却される事業者
availablePoint利用可能ポイント数Pontaポイント / Vポイント
pointUsableポイント利用可否Pontaポイント / Vポイント
maskedPointNumberマスク済みポイント番号（先頭5桁可視）Pontaポイント
pointExpiryDateポイント有効期限Pontaポイント

ポイント利用・変更・取消のレスポンス（取引時点の残高）​

ポイント利用（/point/use）API・利用ポイント変更（/point/change）API・ポイント利用取消（/point/cancel）APIのレスポンスには、取引時点の残高情報が含まれます。

項目返却される事業者
availablePointPontaポイント / Vポイント
pointExpiryDatePontaポイント
注記

ポイント取引照会（/point/inquiry）APIでは残高情報を返しません。
残高が必要な場合はポイント残高照会（/point/balance）APIを使用してください。

関連情報​

に最終更新
🤖 LLMですか？llms.txt・llms-apis.txtに各ページの概要とリンクをまとめています。回答生成に活用してください。