ポイント 処理フロー
処理ごとの手順と注意点を説明します。
全体の流れはOpenAPIタイプ ポイント 処理フローを参照ください。
ポイント認可
ポイントの残高照会・利用・付与を行う前に、お客様のポイント口座と加盟店様の会員IDを紐づけます。
手順
- ポイント認可開始（
/point/start）APIを呼び出します。pointAuthorizationInformation.pointTypeにポイント事業者を指定しますpointAuthorizationInformation.memberIdに加盟店様の会員IDを指定しますmerchant.callbackUrlに 必ず 復帰先URLを設定します（成功・失敗ともに同一URLへ復帰します）
- レスポンスの
redirectInformationに従って、お客様をポイント事業者の認証／同意画面へリダイレクトします。 - お客様の認可手続きが終わると、
merchant.callbackUrlにコールバックされます。
クエリパラメーターpをBase64URLデコードするとaccessIdが取得できます。 - ポイント認可結果確認（
/point/memberinquiry）APIにaccessIdを指定し、認可結果を確認します。
認可結果の判定
status | 意味 | 加盟店様の対応 |
|---|---|---|
REGISTER | 認可済み | ポイント利用・付与を実行できます。pointAccountReference を保存してください |
REGISTERFAIL | 認可失敗 | お客様に失敗を通知し、取引を中止してください。理由は errorInformation を参照 |
REQSUCCESS | 認可依頼受付済み | お客様の認可操作が未完了です。時間をおいて再確認してください |
UNPROCESSED | 認可手続き途中 | 同上 |
すでに認可済みのお客様を再認可した場合も status は REGISTER を返します。
このとき errorInformation.providerCode にポイント事業者の原コード（例：Vポイントの 22-101 ＝既連携）が設定されますが、認可済みであることに変わりはなく、そのままポイント利用・付与が可能です。
pointAccountReference の保持
ポイント認可結果確認（/point/memberinquiry）APIで取得した pointAccountReference は、以降のポイント利用・付与で必要になります。
加盟店様側で、会員とポイント事業者に紐づけて保存してください。
Pontaポイントでお客様が複数のカードを保有している場合は、同一のポイント事業者に対して pointAccountReference が複数払い出されます。どのカードを操作対象にするかを加盟店様側で選択できるようにしてください。
残高照会
ポイント残高照会（/point/balance）APIで、お客様の保有ポイント数とポイント利用可否を取得します。
PayPayポイントは残高照会に対応していません。pointInformation.pointType に PAYPAY は指定できません。
typeに用途を指定しますtransaction：決済直前の残高確認（ポイント利用UIの表示・上限抑止）screen：会員ページ等での保有ポイント表示
- 1リクエストにつき1事業者です。複数事業者を表示する場合は事業者ごとに呼び出してください
pointInformation.pointAccountReferenceは、ポイント事業者を問わず必須です（ポイント利用・ポイント付与と同様）
pointUsable を必ず確認してくださいポイント事業者がお客様のポイント利用を抑止している場合（お客様が初期状態、ポイント利用停止など）でも、照会自体は成立するため HTTPステータスは 200 が返ります。
このとき pointUsable に false が返り、抑止理由が判別できる場合は providerCode が設定されます。
残高（availablePoint）が返っていても pointUsable が false のことがあります。
ポイント利用可否の判定には必ず pointUsable を使用し、false のときはポイント利用をお控えください。
ポイント利用
ポイント利用（/point/use）APIでポイントを代金に充当します。
useInformation.usePointに利用ポイント数（1以上）を指定しますpointInformation.pointAccountReferenceは、ポイント事業者を問わず必須ですpointInformation.transactionInformationのsalesAmount（1以上）／paymentOrderId／receiptNoは、ポイント事業者を問わず必須です- 法令やその他規約等によりポイント利用の対象外とする金額は
useInformation.useExcludeAmountに指定します（消費税相当額は対象に含めます）
同一の購買取引に対してポイント利用とポイント付与の両方を行う場合は、両者に同一の paymentOrderId を設定してください。
ポイント利用を行った取引では、付与ポイントが 0 の場合でもポイント付与の依頼が必須です。
詳細は制約事項と運用ルールを参照ください。
Pontaポイントでは、保持している pointAccountReference をそのまま指定してポイント利用を行うことはできません。
残高照会 → 都度認可 → pointAccountReference の一致確認 → 利用 の順序で実行してください。
詳細は事業者別の仕様差異 - 運用フローの差異を参照ください。
利用ポイント数の変更
利用ポイント変更（/point/change）APIで、変更後の利用ポイント数を指定します。
- Pontaポイント・Vポイントで対応しています（PayPayポイントは非対応）
- 減額のみ 受け付けます。増額および同額変更はできません
- 1取引につき1回まで です。2回目以降は
transaction_count_exceededが返ります paymentOrderIdは元取引から引き継がれるため指定は任意です- 受付期限があります。詳細は制約事項と運用ルールを参照ください
- 購買金額の減額が発生した場合は、利用ポイント数は変更せず、ポイント以外の決済手段の金額から先に減額してください（制約事項と運用ルール）
利用の取消
ポイント利用取消（/point/cancel）APIで、accessId に元取引を指定します。
- 全額取消のみ です。部分取消はできません
- ポイント利用APIが失敗した場合も、本APIで取消してください
- 受付期限があります。詳細は制約事項と運用ルールを参照ください
ポイント付与
ポイント付与（/point/grant）APIでお客様にポイントを付与します。
付与は非同期処理です。 リクエスト受付時点で 202 Accepted を返し、ポイント事業者への処理は非同期に実行されます。
お客様の購入・配送が確定し、商品キャンセル等が発生しないタイミング（着荷後・売上確定後など）以降で付与を行ってください。
付与を前倒しすると、取り戻せない付与取消のリスクを加盟店様が負うことになります。詳細は制約事項と運用ルールをご確認ください。
pointInformation.pointAccountReferenceは、ポイント事業者を問わず必須です- PayPayポイントでは
pointInformation.transactionInformation.paymentOrderIdが必須です。 購買取引に紐づかないポイント付与はお受けできません
手順
grantInformation.pointsにポイント付与明細（categoryとamount）を設定します。grantInformation.webhookUrlに結果通知先URLを設定します。pointInformation.transactionInformation.pointEventDatetimeに、ポイント発生事象（売上確定など）の日時をYYYYMMDDHHMM形式で設定します。未来の日時は指定できません。202 Acceptedを受け取ります（orderReference.statusはREQSUCCESS）。webhookUrlへのポイント付与完了通知API、またはポイント取引照会（/point/inquiry）APIで処理結果を確認します。
売上を伴わないキャンペーン付与などでは、salesAmount と itemCount に 0 を指定できます。ただしPayPayポイントでは購買取引に紐づかないポイント付与をお受けできないため、paymentOrderId の指定が必要です。
ポイントカテゴリ
grantInformation.points[].category には以下を指定できます。
category | 説明 |
|---|---|
REGULAR | 通常ポイント |
BONUS | ボーナスポイント |
points の各明細には、それぞれ異なる category を設定してください。 同一の category を持つ明細を複数含めることはできません。
また、PayPayポイントは REGULAR の1明細のみです。
ポイント事業者によって指定できる組み合わせが異なります。対応外の組み合わせを指定した場合は invalid_parameter が返ります。
詳細は制約事項と運用ルールを参照ください。
付与の取消
ポイント付与は、商品キャンセル等が発生しないタイミング（購入・配送確定後）に実施することが加盟店様運用の前提です。
ポイント付与取消（/point/grantcancel）APIは障害対応等の例外的な操作として扱い、通常の業務フローに組み込まないでください。
詳細は制約事項と運用ルールをご確認ください。
やむを得ず付与を取り消す場合は、ポイント付与取消（/point/grantcancel）APIで accessId に元の付与取引を指定します。
- 実施の直前にポイント残高照会（
/point/balance）APIでお客様の残高を確認し、取消対象のポイント数に対して残高が不足している場合はリクエストしないでください - 全額取消のみ です。部分取消はできません
- 一度成功した付与取消は再実施できません。 2回目の付与取消は
invalid_statusで拒否されます - 付与取消も非同期処理です。完了は、元の付与時に設定した
grantInformation.webhookUrlへのポイント付与取消完了通知APIで確認します - 受付期限があります。詳細は制約事項と運用ルールを参照ください
お客様が付与されたポイントを既に使用している場合、取り戻せる範囲はお客様が残高として保持している分に限られます。
部分的にしか取り戻せなかった場合も付与取消は成功として通知されるため、pointResult.errorPoint を必ず確認してください。
詳細は制約事項と運用ルールを参照ください。
結果が不明な場合の確認
orderReference.status が UNPROCESSED の場合や、通信エラー等で結果を受け取れなかった場合は、ポイント取引照会（/point/inquiry）APIで最新の状態を確認してください。再送する場合の手順は制約事項と運用ルールを参照ください。
accessIdとorderIdのどちらかを指定します- 取引種別（利用／付与）は
pointResult.transactionTypeで判別します orderReference.statusが確定状態（USE/USECANCEL/GRANT/GRANTFAIL/GRANTCANCEL）になるまで確認してください
status が GRANTFAIL（付与失敗確定）の場合、ポイントは付与されていないため取消は不要です。