ポイント 制約事項と運用ルール
ポイント事業者の仕様・運用に起因する制約と、加盟店様側で実装いただく必要がある事項をまとめています。
パラメーターの型・桁数はAPIリファレンスを、事業者ごとに異なる制約は事業者別の仕様差異を参照ください。
本ページの制約のうち、当サービスでは検証できず加盟店様側での対応が必要なものがあります。
特に「ポイント付与の実施タイミングと付与取消の位置づけ」と「付与取消で取り戻せる範囲」は、返品・返金業務の設計に直結します。
ポイント利用時はポイント付与の依頼が必須です
ポイント利用（/point/useAPI）を行った取引では、ポイント付与（/point/grantAPI）の依頼が必須です。
付与するポイントが発生しない場合も、付与ポイント数 0（grantInformation.points[].amount に 0）でポイント付与を依頼してください。 依頼を省略することはできません。
ポイント利用とポイント付与には、同一の pointInformation.transactionInformation.paymentOrderId を設定してください。
購買金額が減額された場合の扱い
購買金額の減額（部分返品・部分キャンセル等）が発生した場合は、ポイントの利用ポイント数は変更せず、ポイント以外の決済手段の金額から先に減額してください。
利用ポイント数を減額するのは、他の決済手段の金額をすべて減額してもなお減額しきれない場合に限ってください。
- 利用ポイント数を変更できるのはPontaポイント・Vポイントで、1取引につき1回までです（PayPayポイントは利用非対応）
購買取引を全額取消・全額返金する場合は、ポイント利用取消（/point/cancel）APIでポイント利用を取り消してください。
決済取引との紐づけ
購買を伴うポイント取引では、pointInformation.transactionInformation.paymentOrderId に対応する決済取引のオーダーIDを設定してください。
同一の購買取引に対してポイント利用とポイント付与の両方を行う場合は、両者に同一の paymentOrderId を設定してください。
PayPayポイントでは、購買取引に紐づかないポイント付与をお受けできません。 ポイント付与（/point/grant）APIでも、対応する決済取引のオーダーIDを paymentOrderId に必ず指定してください。
同一の paymentOrderId に対して、同一のポイント事業者（pointInformation.pointType）による付与は1回のみです。 同一 paymentOrderId ・同一ポイント事業者で2回目のポイント付与（/point/grantAPI）をリクエストした場合はエラーになります。
ポイント付与明細
grantInformation.points の指定にあたり、以下の制約があります。
指定できるカテゴリは事業者ごとに異なります
| ポイント事業者 | 指定できる category |
|---|---|
| Pontaポイント | REGULAR / BONUS |
| Vポイント | REGULAR / BONUS |
| PayPayポイント | REGULAR のみ |
対応外の組み合わせを指定した場合は invalid_parameter が返ります。
Vポイントで BONUS を利用する場合は、事前に当社営業担当と実施内容をすりあわせてください。
売上金額の考え方
加盟店様独自のクーポン・商品券等で値引きが発生した場合、売上金額（ポイント付与対象金額）は値引き後の金額としてください。
例：10,000円の商品がセール価格で9,000円になる場合、売上金額は9,000円、付与ポイント数は90ポイントとなります。
消費税相当額は、ポイント付与の対象金額に含めます。
useInformation.useExcludeAmount / grantInformation.grantExcludeAmount は、法令やその他規約等によりポイントの利用・付与の対象外とする金額（たばこ・金券等の一部商品）を指定する項目です。
ポイント付与の実施タイミングと付与取消の位置づけ
お客様の購入・配送が確定し、商品キャンセル等が発生しないタイミング（着荷後・売上確定後など）以降に付与を行うことが、加盟店様運用の大前提です。
ポイント付与取消（/point/grantcancel）APIは、やむを得ない場合（障害対応等）に限定した例外的な操作です。いつでも実行できる通常の操作として業務フローに組み込まないでください。
理由は以下のとおりです。
- 一度成功した付与取消は再実施できません。 元取引に対する2回目の付与取消は
invalid_statusで拒否されます - 付与したポイントがお客様に使用されていると、取り戻せません。 取り戻せる範囲はお客様が残高として保持している分に限られます（付与取消で取り戻せる範囲）
- 付与から反映までに時間差があります。 付与直後の取消は、お客様側の残高状態が確定していない状態での操作になります
付与のタイミングを前倒しすると、これらのリスクを加盟店様が負うことになります。付与は「取消が不要になってから」実施してください。
付与結果の反映タイミング
ポイント付与・ポイント付与取消は、すべてのポイント事業者で非同期処理です。即時反映を前提とした設計にしないでください。
処理結果はWebhook通知またはポイント取引照会（/point/inquiry）APIで確認してください。
お客様のポイント残高に反映されるまでの目安は、加盟店様の付与リクエストから4〜5日後です。ポイント事業者側の処理状況により、前後する可能性もございます。
お客様へポイントの付与を案内する場合は、この期間を考慮した表現としてください。
取消・変更の受付期限
受付期限を超過したリクエストはエラーになります。返品・キャンセル業務の設計時にご考慮ください。
| ポイント事業者 | 受付期限 |
|---|---|
| Pontaポイント | 元取引が属する月の翌々月末日まで |
| Vポイント | 元取引から180日以内 |
| PayPayポイント | 元取引から180日以内 |
ポイント利用取消・利用ポイント変更・ポイント付与取消の3操作すべてに適用されます。
期限の起点は操作によって異なります。
| 操作 | 期限の起点 |
|---|---|
| ポイント利用取消 / 利用ポイント変更 | 元取引の処理日時 |
| ポイント付与取消 | 元付与（/point/grantAPI）のリクエストで指定した pointEventDatetime（ポイント発生事象日時） |
ポイント付与取消のリクエスト自体には pointEventDatetime を指定しません。 期限は、取消対象となる元の付与リクエストで指定した pointEventDatetime を基準に判定されます。
付与取消で取り戻せる範囲
実施の前にポイント付与の実施タイミングと付与取消の位置づけをご確認ください。
付与取消では、取り戻せる範囲を加盟店様側で制御できません。
ポイント付与取消では取消するポイント数を指定できません。 依頼は常に元取引の全額に対して行います（部分取消を指定した場合は unsupported_operation が返ります）。
ただし依頼が全額でも、全額を取り戻せるとは限りません。 お客様が付与されたポイントを既に使用している場合、取り戻せる範囲はお客様が残高として保持している分に限られます。
付与取消の前に残高を確認してください
やむを得ず付与取消を実施する場合は、直前にポイント残高照会（/point/balance）APIでお客様の残高を確認し、取消対象のポイント数に対して残高が不足している場合は付与取消をリクエストしないでください。
お客様のポイント残高がマイナスになることは、ポイント事業者の運用上認められていません。残高不足のまま付与取消を実施した場合の結果は事業者ごとに異なり、いずれの場合も加盟店様側での損失につながります。
取り戻せなかったポイント数の確認
| ポイント事業者 | 部分的な取り戻し | 取り戻せなかったポイント数 |
|---|---|---|
| Pontaポイント | 発生しません（全額取消の成功／失敗のいずれか） | — |
| Vポイント | 発生します | pointResult.errorPoint |
| PayPayポイント | 発生します | pointResult.errorPoint |
pointResult.errorPointは「付与取消できなかったポイント数」です。全額を取り戻せた場合は0です- 部分的にしか取り戻せなかった場合も、ポイント付与取消は成功として通知されます。 Webhook通知の種別や
orderReference.statusでは全額成立と部分成立を区別できません。errorPointを必ず確認してください - 依頼の時点で部分成立するかどうかは判定できません。 付与取消は非同期のため、結果はWebhook通知またはポイント取引照会（
/point/inquiry）APIで確認してください - 取り戻せなかったポイント数に対して、付与取消を再度実行することはできません。 一度完了した元取引に対する2回目の付与取消は
invalid_statusで拒否されます
付与取消だけでは損失を全額回収できない場合があります。
取り戻せなかった分の扱い（お客様への請求、加盟店様側での負担等）は、加盟店様の業務設計でご対応ください。
結果が不明な場合の再送
通信エラーなどで結果を受け取れなかった場合は、初回リクエストと同一の冪等キー（Idempotency-Key）・同一の order.orderId で再送してください。
値を変更すると別取引として扱われ、二重処理になります。
冪等処理の詳細はリクエスト仕様 - 冪等処理を参照ください。
再送せずに状態を確認する場合はポイント取引照会（/point/inquiry）APIをご利用ください。詳細は処理フローを参照ください。
見なし処理（provisional）
当サービスとポイント事業者間の通信で確定結果を受け取れなかった場合でも、成功応答を返すという事業者との取り決めがあります。
この場合、レスポンスの provisional を true として返却します。取引ステータス（orderReference.status）は、通常の成立時と同じ値を返します（例: ポイント利用なら USE）。
provisional が true の場合でも、加盟店様側で対応いただくことはありません。 リトライ（再送）は不要です。
ただし、成功レスポンスを返していても、ポイント事業者側での実際の利用・取消処理は即時に完了するとは限らず、後日行われることがあります。
対象はポイント利用（/point/use）API・利用ポイント変更（/point/change）API・ポイント利用取消（/point/cancel）APIの3操作です。
ポイント付与（/point/grant）には見なし処理の概念はありません。
結果が不明な場合の再送は、通信エラー等で応答自体を受け取れなかった場合の対処です。
見なし処理は、そのような場合でも事業者との取り決めにより成功応答（provisional=true）が返る場合を指します。応答自体は受け取れているため、再送してはいけません。