Rewald（リワルド）ポイントシステム 技術仕様・実装ガイド（改訂版 ver01.3）

1.0 はじめに

1.1. Rewald（リワルド）の概要

Rewald（リワルド）は、クレジット決済事業者の制約を受けることなく、Webサイトやモバイルアプリなどの環境に独自の報酬ポイントプログラムを発行・展開するための仕組みを提供します。この実装ガイドに基づきポイント処理システムを設計・開発することで、あなたのサービス利用者エンゲージメントや顧客ロイヤルティを飛躍的に高める新たな付加価値をもたらすことが期待できます。

Rewald（リワルド）は以下に掲げる基本的な考えに基づき、なるべく誰もが比較的手軽に自分たち独自のポイント発行プログラムを実現できる仕組みを目指しています。

実装の簡潔さ: WordPressで構築された環境では、HTMLタグとショートコード（機能別コード）の組み合わせのみで、必要なポイント処理を完結させることができます。また、ショートコード（機能別コード）はPHP関数形式を用いた実装もサポートしていることから、独自開発のPHPプログラム環境でもRewald（リワルド）の全機能をご利用頂けます。

作業負担の軽減: 複雑になりがちなポイント処理を8つの機能別コードに分類し、専用のAPIバックエンドと連携することによって全体を抽象化。これにより、稼働形態の環境差異を吸収し、実装時の開発コストを大幅に削減します。

高い拡張性と柔軟性: 各機能別コードには「callback」属性が用意されており、この機構を活用するとあなた独自の処理を容易に追加することも可能です。この仕組みがあることで実装環境全体の柔軟性も確保でき、将来的な機能拡張にも充分配慮できる設計・開発環境を提供します。

このガイドは実装・開発に着手する前の環境設定から各機能の実装方法、そして運用上の注意点など、Rewald（リワルド）をつかったポイント処理システムの構築に必要な情報を詳細且つ網羅的に解説します。まずは開発の第一歩となる「導入準備」から始めましょう。

2.0 導入準備

2.1. 用意が必要なもの

実装を開始するにあたり、以下の2つの要素が不可欠です。

Rewald（リワルド）が発行する「環境設定コード」: API連携に必要な認証情報を含む、利用者固有の識別コードです。

Webサイトやモバイルアプリの開発に必要となる「管理者権限」: WordPressの場合はテーマファイルやサイトのコア設定にアクセスするための権限。独自のPHPプログラムの場合は、サーバー上のPHPファイルやテンプレートファイルを直接編集できる権限（FTP/SSHアクセス権限など）が必要となります。

環境設定コードの取得方法
環境設定コードには、APIと連携するための制御命令と利用者識別情報が含まれています。以下のURLより申請・取得してください。

環境設定コードの取得はこちらから

2.2. 環境設定コードの組み込み

環境設定コードの組み込み場所
取得した環境設定コードは、ウェブサイトやモバイルアプリ全体で読み込まれる場所に設置する必要があります。利用環境に応じて、以下の適切な場所にコードをコピー＆ペーストしてください。

警告： 認証情報の取り扱いについて
この環境設定コードには、ACCESS_TOKENを含む機密性の高い認証情報が含まれています。このコードブロック全体を秘密情報として扱い、ログ・エクスポート時の平文記録を避け、第三者への漏洩が決して発生しないよう厳重に管理してください。環境設定コードの組み込みが完了することで、具体的なポイント処理機能を実装するための基盤が整います。

2.3. 【最重要】利用者識別とデータの永続性（UUID管理）

警告： この項目はシステム安定運用の根幹に関わる最重要事項です。
Rewald（リワルド）は、サイト利用者を識別するために、ブラウザのCookieに独自のUUID（Universally Unique Identifier）を保存します。このUUIDをキーとして、個々の利用者のポイント情報を管理します。しかし、Cookieを利用するこの方式には、ブラウザ間の非互換性（クッキーはブラウザを跨いで利用不可）やユーザー自身によるCookieの削除といった、本質的な課題が存在します。例えば、あるユーザーがPCのChromeブラウザでポイントを獲得した後、スマートフォンのSafariブラウザでアクセスした場合、ポイント情報を引き継ぐことはできません。

この課題への唯一の解決策は、サイト運営者やモバイルアプリ開発者が保有する顧客データベースとRewald（リワルド）のUUIDの紐付け処理を独自に実装することです。利用者がログインした際に、運営者側の顧客IDとRewald（リワルド）のUUIDを関連付けることで、デバイスやブラウザが変わってもポイント情報を永続的に保持することが可能になります。この実装は、ポイント情報の永続性を担保し、安定したサービスを提供するために不可欠です。

実装例: 利用者のログイン成功後、Rewald（リワルド）のUUIDをCookieから取得します。次に、そのUUIDをサイトのユーザーデータベーステーブルに保存し、サイト固有のユーザーIDと関連付けます。利用者が新しいデバイスでログインした際には、データベースにUUIDが保存されているかを確認し、存在されていれば、そのUUIDを用いてRewald（リワルド）とポイント情報を同期します。この実装によって、ログインさえすればデバイスを問わずポイント情報を永続的に保持できます。

※ 補足：ショートコード（機能別コード）間の状態連携と sessionStorage の併用
Cookie/UUID が「利用者の識別とポイント残高の長期的な永続性」を担うのに対し、Rewald（リワルド）のクライアントサイド処理では、ブラウザの sessionStorage も内部的に併用しています。sessionStorageはポイント計算の予測値・取引用 nonce（ワンタイムトークン）・トランザクションの状態情報など、単一のブラウザタブ内で完結する一時的な取引状況を安全に管理するために利用されます。

この仕組みには主に3つの特徴があります。①タブ単位の独立性です。ブラウザのタブ（またはウィンドウ）ごとに独立したスコープを持つため、利用者が複数のタブを同時に開いて異なる商品の購入操作を進めても、各々の取引データが入り混じってしまう状態を確実に防ぎます。②ページ遷移への強度耐性です。同じタブ内での画面遷移や、PayPal・Stripeなどの決済代行サービス（PSP）へのリダイレクト前後においても、一時的な取引状態を維持し、処理を安全に再開できる基盤を提供します。③ライフサイクルの自動管理です。ユーザーがタブを閉じた時点でデータは自動的にクリアされる設計となっているため、開発者が手動での保存・削除処理や競合制御を実装する必要は一切ありません。このように「Cookie（長期識別・永続管理）」と「sessionStorage（短期取引状態・タブ内連携）」が明確に役割分担することで、Rewald（リワルド）は高いセキュリティと安定した決済フローを実現しています。開発者は複雑な状態管理ロジックを記述することなく、ショートコード（機能別コード）の配置だけで安全なポイントトランザクションを構築できます。

3.0 Rewald（リワルド）が実現するポイント処理の基本的な考え方と実装手法

3.1. ポイント処理の全体像

個別のショートコード（機能別コード）を解説する前に、Rewald（リワルド）がどのようにポイント処理を実現しているか、その全体的な仕組みと設計指針を理解することが重要です。Rewald（リワルド）のポイント処理は、特定のユースケースに応じて設計された、以下の8つのショートコード（機能別コード）の組み合わせによって実現されます。

1. [point_setting] 基礎情報の設定 (通貨/料率などの定義)

2. [point_trans_open] 決済データと紐付け ※point_trans_previewに名称変更

3. [point_trans_close] ポイント処理完了フラグ ※point_trans_readyに名称変更

4. [point_trans_detail] 実行結果の通知

5. [point_trans_cancel] ポイント処理キャンセル時の通知

6. [point_own] 獲得済みポイント数の表示

7. [point_purchase_open] ポイントの購入処理開始

8. [point_purchase_close] 決済金額を確定した後、指定のポイント数を付与

3.2. 実装手法の比較

Rewald（リワルド）は利用環境に合わせて、以下の2つの記述方式を提供しています。

WordPress環境

記述方式: ショートコード形式 [...]

設置場所: 投稿・固定ページ、ウィジェット内など

独自開発サイト (PHPプログラム)

記述方式: PHP関数形式 <?php point_xxx(array(...))?>

設置場所: PHPテンプレートファイル内（HTMLとの混在可）

4.0 標準トランザクション実装（商品購入時のポイント利用）

Rewald（リワルド）のクライアントサイド処理は非同期で実行されます。そのため、システム全体を通してcallbackパターンが中心的な役割を果たします。各ショートコード（機能別コード）のcallback_name属性は、ポイント計算後の最終金額や処理結果といった非同期処理の結果を受け取り、サイト独自のJavaScriptロジック（例：決済代行会社のSDKへデータを渡す処理）と連携するための指定されたメカニズムです。このアーキテクチャを理解することが円滑な実装の鍵となります。

4.1. 実装フローの概要（機能別コード・詳細リファレンス）

このセクションでは、顧客が商品を購入する際にポイントを「利用」または「獲得」する場合の最も基本的な処理フローについて解説します。一連の処理は複数のショートコード（機能別コード）を適切なページに順を追って設置することで実現されます。

4.2. [point_setting] 基礎情報の設定

役割: ポイント処理を実行するにあたっての基礎情報（通貨、レート）を定義し、セッションを初期化します。

設置場所: ポイント取引が行われるページの先頭付近。通常は商品価格タグとポイント利用項目フィールドが共存するページに、後続の取引系ショートコードより前に設置することが推奨されます。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response) (内部仕様では第2引数に null が渡されますが、実装時は第1引数のみ参照します)
• 引数構造:
  • response: 設定結果を含むオブジェクト（PointSystemResult<PointSettingResult>）。
  • response.error: エラー発生時のメッセージ（成功時は null または undefined）。
  • response.result: 初期化された設定情報。
    • session_token: セッション識別トークン。
    • currency_type: 適用された通貨コード。
    • conv_rate: 適用された還元率。
    • use_rate: 適用された使用率。
• 用途: 設定が正しく反映されたことを確認したり、セッション初期化完了後の UI 表示制御に使用します。成功実行後、設定情報はブラウザ Cookie point_setting に自動的に保存されます。

実装時の注意点:
料率の記述ルール: 料率の指定は個別属性（conv_rate および use_rate）か集約属性（rate）のいずれか一方のみを使用してください。両方の形式を同一コード内で混在させた場合、API_ERROR_BAD_REQUEST が返されます。
セッションとCookie管理: このショートコードの実行には、ユーザー識別 Cookie point_system_account_name が事前に設定されている必要があります。実行後、設定情報は Cookie point_setting（JSON形式）として保存され、有効期限は365日に設定されます。後続のショートコードはこの Cookie を自動的に参照して処理を継続します。

4.3. [point_trans_preview]（旧: point_trans_open）決済データとの紐付け

役割: 価格・ポイント入力要素を監視し、変更があるたびに API へ送信して「最終支払金額」と「ポイント計算結果（予測値）」を再計算・通知します。

設置場所: ポイント利用項目（利用の有無そのものや数値を入力する欄）と購入商品の合計金額両方が表示されるページに設置してください。

実装時の注意点:
このショートコードは多くの場合、前項で解説している [point_setting] と一対で商品注文時の最終確認画面ページに設置されることが推奨されます。
Rewald（リワルド）のポイント計算処理は「決済時の合計金額」に対してのみ適用される仕様です。ショッピングカート内の商品個別の価格に対して、それぞれ計算する設計にはなっておらず、常に合計金額を一つの価格単位として扱います。
入力要素には input[type="text"]、input[type="hidden"]、input[type="number"]、または div が公式にサポートされています。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response, null) （注: システム内部仕様として第2引数は常に null が渡されます。実装上は第1引数の response のみを使用します）
• 引数構造:
  • response: 計算結果を含むオブジェクト（PointSystemResult<PointTransOpenResult>）。
  • response.result.total_price: ポイント利用額を差し引いた後の最終お支払い金額（文字列）。
  • response.result.use_point: 今回利用されるポイント数（数値）。
  • response.result.price: 商品元の価格（文字列）。
  • response.result.point: 現在の保有ポイント数（数値）。
  • response.result.new_point: 現時点の入力で確定した場合の獲得予測ポイント数（数値）。
  • response.result.total_point: 現時点の入力で確定した場合の残高予測値（数値）。
  • response.result.trans_closed_at: 確定時刻（open 時点では常に null）。
  • response.result.pointsystem_nonce: このトランザクション固有の nonce トークン（後続処理で必須）。
• 注意:
  • new_point および total_point はこの段階では予測値として返されます。これらが「確定値」として固定されるのは、後続の point.close() 実行後、または [point_trans_detail] 呼び出し後です。
  • 金額関連プロパティ（total_price, price）は文字列です。数値演算や決済 SDK へ渡す場合は parseFloat() または String() 等で適切に変換してください。
  • conv_point や grant_point といったプロパティ名は存在しません。正しいプロパティ名は new_point です。
• 用途: 画面に表示されている「お支払い金額」を動的に更新したり、金額が 0 円になった場合に決済ボタンの表示/非表示を切り替えるロジックで使用します。入力値が変更されるたびに非同期で発火し、最新の計算結果と pointsystem_nonce が sessionStorage に上書き保存されます。

4.4. [point_trans_ready] (旧: [point_trans_close]) ポイント処理完了（重要：動作の理解）

役割: トランザクション制御オブジェクト（PointInstance）を生成し、後続の決済処理（PayPal/Stripe 連携など）をセットアップするための「初期化通知」を行います。

設置場所: 注文確定（決済）ボタンが設置されるページに配置してください。

⚠️ 重要: このコールバックは「close が完了した瞬間」ではなく、「close を実行できる準備が整った瞬間（初期化通知）」に発火します。第 1 引数には new_point / total_point などが予測値として含まれますが、これらは確定値ではありません。確定値は point.close() の戻り値として取得します。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response, point)
• 第 1 引数 response:
  • 内容: { result: PointTransOpenResult }
  • 意味: これは point_trans_preview (旧 point_trans_open) の結果を包んだものです。
  • 含まれるプロパティ: total_price, use_point, price, point, pointsystem_nonce、および予測値としての new_point, total_point, trans_closed_at など（PointTransOpenResult の全フィールド）。
  • 注意点: ここに含まれる new_point / total_point はあくまで「現時点の入力で確定した場合の予測値」です。確定値は point.close() を実行した後の戻り値、または [point_trans_detail] で取得します。
• 第 2 引数 point (PointInstance):
  • 意味: トランザクションを制御するためのオブジェクトの実例。
  • 主要プロパティ:
  • price, total_price, use_point: open 結果からの引き継ぎ。
  • open_result: open 結果のフルオブジェクト。
  • pointsystem_nonce, token: 認証用トークン。
  • url: REST API のベース URL。
  • data: { token, pointsystem_nonce }（キャンセル時の POST ボディとしてそのまま使用可能）。
  • 主要メソッド:
  • point.close(): Promise\ を返す。ポイントを確定（残高変動・nonce消費）させる。戻り値に new_point, total_point などの確定値が含まれる。
  • point.cancel(): void。トランザクションを取り消し、確定済みのポイントを元に戻す（ロールバック）。
  • bindEvent(id): void。指定した要素の onclick に close() をバインドする便利メソッド。
• 用途:
  1. ポイント利用（use_point > 0）がある場合、PSP処理（PayPal/Stripe）の前に await point.close() を呼び出し、ポイントを確定させて二重利用を防ぐ。
  2. PSP処理が失敗またはキャンセルされた場合、await point.cancel() を呼び出して確定済みのポイントを復元する（ロールバック）。
• Close 結果（PointTransCloseResult）の取得方法（3 パターン）:
  1. 同一ページ内: var result = await point.close() の戻り値を確認。
  2. 別ページ: [point_trans_detail] ショートコードを使用（sessionStorage の pointsystem_last_closed_nonce を基に結果を取得）。
  3. PSP 検証付き: REST API GET /wp-json/pointsystem/v1/point_trans_close/?orderId=...&customId=... を使用（シナリオ B/C）。

実装に関する補足: callback_name の第 1 引数 response.result.total_price を参照することで、全額ポイント利用などで費用が発生しない「金額ゼロ」の場合における処理分岐に利用できます。 例えば、金額が 0 円以下の場合は PSP（PayPal/Stripe）のボタンを表示せず、point.close() を実行した後に完了ページへ直接遷移させる、といった制御のトリガーとして用います。

また、ポイント利用がある場合は必ず PSP 遷移前に point.close() を実行し、nonce を消費して残高をロックする必要があります。これにより、PSP処理中に別タブでポイントが二重利用されるのを防ぎます。PSP失敗時は必ず point.cancel() を呼び出してロールバックしてください。

4.5. [point_trans_detail] 実行結果の通知 ※260602時点、llmsの情報更新が必要（詳細不足をQwen指摘。推論補完したので）事実確認後の更新対応となって、次回MTGまでに対応するとの認識（片桐）

役割: 確定済みのトランザクション詳細（利用ポイント、獲得ポイント、残高など）を取得・表示します。通常、決済完了ページで使用されます。

設置場所: 決済処理が正常に行われて注文完了をお知らせする為のページに設置してください。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response)
• 引数構造:
  • response: 詳細情報を含むオブジェクト（PointSystemResult<PointTransCloseResult>）。
  • response.result.use_point: 利用ポイント数。
  • response.result.new_point: 今回付与されたポイント数。
  • response.result.total_point: 現在の総保有ポイント数。
  • response.result.trans_closed_at: 確定時刻（文字列または null）。
  • response.result.is_trans_canceled: 取消フラグ（文字列または null）。
  • response.result.trans_canceled_at: 取消時刻（文字列または null）。
• 注意: transaction_id プロパティは現在の仕様では保証されていません。主に use_point, new_point, total_point を使用してください。
• 用途: 決済完了ページなどで、ユーザーに対して「今回の利用内訳」と「新しい残高」を表示するために使用します。

4.6. [point_trans_cancel] キャンセル処理 ※260602時点、llmsの情報更新が必要である。実装検証後の更新作業となるので次回MTGまでに対応するとの認識（片桐）

役割: トランザクションをキャンセルし、ポイントを復元した旨を通知します。

設置場所: 注文キャンセルページなど、処理が取り消されたことをユーザーに通知するページに設置します。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response)
• 引数構造:
  • response: キャンセル結果を含むオブジェクト（PointSystemResult<PointTransCloseResult>）。
  • response.error: キャンセル失敗時のエラーメッセージ（成功時は null または undefined）。
  • response.result.use_point: 取り消された利用ポイント数。
  • response.result.new_point: 取り消された付与ポイント数（取消対象だった場合）。
  • response.result.total_point: 取消処理後の現在の残高。
  • response.result.is_trans_canceled / .trans_canceled_at: 取消フラグおよび時刻。
• 実装上の注意点:
  • 戻り値に message 文字列は含まれません。成功判定は response.error の有無で行ってください。
  • response.result.restored_point のような専用プロパティは存在しません。通常は response.error が無いこと、および point.cancel() / ショートコード実行の成功自体をもって復元完了とみなします。
  • UX 向上のため、「トランザクションがキャンセルされました。ポイントは復元されました。」といったメッセージ表示を行う場合は、フロントエンドの JavaScript 側で文言を管理・出力することを推奨します。
• 用途: キャンセル専用ページなどで、ユーザーに処理完了を通知し、復元後の残高（response.result.total_point）を表示するために使用します。

以上が標準的なユースケースとして発生し得る商品購入時に対応するポイント処理の流れです。

次に特殊なトランザクションであるポイントそのものを購入する場合の処理について解説します。

5.0 ポイント購入のための処理実装

5.1. 実装の流れと技術的考察

ポイント購入の処理は商品購入時のポイント利用や獲得の流れとは異なり、決済の失敗やキャンセル時にポイントが不正に取得されるリスクを伴います。そのため、特に慎重な設計と思慮深い実装が求められます。

この処理の実装が技術的に難しい理由は以下の点にあります。

脆弱性の発生: 商品購入時には「先にポイントを確保してから決済する」という実装ロジックを実現してますが、この処理ロジックを踏襲すると決済がキャンセルされた場合にポイントだけが不正に取得される脆弱性が生まれます。

決済代行業者（PSP）への適合: 決済代行業者（PSP）の仕様、例えば費用が発生しない金額ゼロ決済時のハンドリングや決済額が確定した後に動的に決済ボタンが生成される仕様など、外部システムの要件に適合させながらRewald（リワルド）でポイント処理を実装する必要があります。

5.2. [point_purchase_open] ポイント購入処理の開始 ※260602時点のQwen認知学習結果レビュー未実施のため、次回MTG以降の評価予定

役割: ポイント購入の初期化を行います。呼び出しモードによってコールバックの引数が完全に異なります。

設置場所: ポイント購入ができるページ

解説: ポイントそのものを購入する為の処理に特化した機能別コードです。内部処理的には商品購入時のポイント消費と違い、最初に決済金額を取得した後、後続のポイント付与処理などを開始します。

【属性一覧】

【callback_name の詳細仕様】

モード A: 価格指定モード（price 属性あり）

• シグネチャ: function(response)
• 引数構造:
  • response: 購入試算結果を含むオブジェクト（PointSystemResult<PointPurchaseOpenResult>）。
  • response.result.pointsystem_nonce: 購入用 nonce トークン。
  • response.result.price: 購入対象金額（文字列）。
• 用途: 通常、非表示の <span> 内に配置し、テキストコンテンツとして nonce を取得するために使用されます。

  <span id="purchase_nonce" style="display:none;">
  [point_purchase_open price="1000" currency_type="JPY" conv_rate="1"]
  </span>
  <script>
  var nonce = document.getElementById('purchase_nonce').textContent.trim();
  </script>

• 注意: purchase_amount, grant_point, currency というプロパティ名は存在しません。

モード B: ポーリングモード（price 省略 + callback_id + callback_name 指定）

• シグネチャ: function(dataset, pointsystem_nonce, signature)
• 引数:
  1. dataset (DOMStringMap): 監視対象ボタンの data-* 属性群（例: data-order-id, data-amount）。
  2. pointsystem_nonce (string): REST API 経由で取得した新しい nonce。
  3. signature (string): order_id|nonce|amount に対する HMAC-SHA256 署名。
• 動作: システムはボタンの data-order-id / data-amount 属性を 100ms 間隔で監視し、変更があるたびに新鮮な nonce と署名を取得してこのコールバックを発火させます。
• 副作用: sessionStorage に pointsystem_<orderId> キーで { dataset, currency_type, conv_rate, amount, pointsystem_nonce, signature } を保存します。
• 用途: クーポン適用や数量変更など、ページロード後に価格が動的に変化するシナリオで使用します。

実装時の注意点:
実装制約: 購入金額を選択式のUIで指定するような実装はサポートされていません。
料率仕様: 「conv_rate」は為替変動の影響を避けるため、等価率（100%）を基準とする固定換算方式を採用しています。
非対応ロジック: 保有ポイントを利用して新たなポイントを購入する、というユースケースは想定されておらず、現実事象としても無意味でもあるため実装できません。

5.3. [point_purchase_close] ポイント購入処理の完了 ※260602時点のQwen認知学習結果レビュー未実施のため、次回MTG以降の評価予定

役割: ポイント購入の決済完了後、正式にポイントが付与された結果を受け取ります。

設置場所: ポイントの購入が正常に終了した事を知らせるページ（いわゆる決済完了ページ）

解説: ポイント購入の為の決済金額を取得したあとの付与ポイント数を確定させて、最終的に購入者にポイント付与を実施します。

⚠️ 重要: シナリオ D, E（ポイント購入）では、このショートコードをページに配置してはいけません。JavaScript の fetch() で REST API /wp-json/pointsystem/v1/point_purchase_close/ を直接呼び出す形式が必須です。

【属性一覧】（参考: ショートコードとしての属性定義）

【callback_name の詳細仕様】（REST API 呼び出し時のレスポンス構造）

• シグネチャ: function(response)
• 引数構造:
  • response: 購入完了結果を含むオブジェクト（PointSystemResult<PointPurchaseCloseResult>）。
  • response.result.point: 付与後のポイント残高（数値）。
  • （その他 PointTransCloseResult 互換のフィールドを含む）
• 注意: transaction_id プロパティは現在の仕様では保証されていません。主に point プロパティを使用してください。

• 実装上の注意:

  • API リクエストボディは JSON.stringify({ order_id: "...", nonce: "...", amount: "..." }) 形式です。キーは session_id ではなく order_id であることに注意してください。
  • レスポンスもこの response 構造と同じ形式になります。

  ---

ポイントそのものを購入するという特殊な処理の解説は以上になります。

次にサイトやモバイルアプリの様々な場所で利用できる汎用的なユーティリティ機能について解説します。

6.0 ユーティリティ機能

このセクションでは、主要なトランザクションフロー以外の補助的な処理を提供するショートコードについて解説します。

6.1. [point_own] 保有ポイント数の表示

役割: 対象ユーザーの現在保有しているポイント数を非同期的にAPIから取得し、フロントエンドへ通知します。

設置場所: ヘッダー、マイページ、商品ページ、購入ページなど、残高表示が必要な任意の場所。特定の制約はありません。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response)
• 引数構造:
  • response: 残高情報を含むオブジェクト（PointSystemResult<PointOwnResult>）。
  • response.error: エラー発生時のメッセージ（成功時は null または undefined）。
  • response.result.point: 現在の保有ポイント数（数値型）。
• 用途: ヘッダーやマイページなど、サイトの任意の場所でリアルタイムに残高を表示するために使用します。実装時は必ず response.error によるガード処理を行ってください。
• 補足: callback_name を省略した場合、ショートコードは自動的に id="point_id" の要素にポイント数を表示します。このフォールバック動作を利用する場合はページ上に該当IDの要素が必須となりますが、エラーハンドリングが不可能になるため、明示的な制御とUX向上のため callback_name 属性の指定を強く推奨します。また、本処理は Cookie point_system_account_name に基づいてユーザーを識別するため、ログイン状態やUUIDの紐付けが正しく設定されていることを事前に確認してください。

📘 補足：コールバック関数の基本ルールと重要な注意点

Rewald（リワルド）のポイント処理は非同期API通信とショートコードの自動注入によって構成されています。実装の安定性とデータ整合性を保証するため、以下のルールを全てのコールバック関数および決済フローで厳守してください。

1. 関数の定義とスコープ

• グローバルスコープ必須: コールバック関数は window.myCallback = function(...) { ... } または HTML 内の <script> タグ直下で定義してください。モジュールスコープやクロージャ内に閉じ込めると、ショートコードが注入するスクリプトから参照できず ReferenceError が発生します。
• DOMContentLoaded ラッパー禁止: ユーザが記述する <script> 内のコードを document.addEventListener("DOMContentLoaded", ...) でラップしないでください。各ショートコードが内部で適切なDOMロードタイミングを吸収しており、二重ラップは実行順序の競合や未定義エラーの原因となります。

2. レスポンス構造の統一（Response Wrapper）

すべてのコールバックに渡される第1引数（通常 response と命名）は、以下の統一構造に従います。

⚠️ 厳守事項:

• 成功時のデータは必ず response.result の下に格納されます。response.point や response.total_price とすると undefined になります。
• 二重ネスト（response.result.result.xxx）は発生しません。変数名とJSONキー名が衝突しないよう、引数名を response や res に統一することを推奨します。

3. エラーハンドリングの定石

コールバックの先頭で必ずエラー有無をチェックし、早期リターンしてください。

function myCallback(response) {
  if (response && response.error) {
    console.warn(`エラー(${response.error_code}): ${response.error_description}`);
    // UIにエラー表示する処理など
    return;
  }
  // 正常系処理
  console.log('取得成功:', response.result);
}

4. 【最重要】point_trans_ready の動作理解

ショートコード名に反し、このコールバックは「トランザクション完了通知」ではなく「Point インスタンス準備完了（初期化）通知」です。

• 発火タイミング: DOMContentLoaded 発火後、かつ sessionStorage に pointsystem_open_result が保存された時点。
• 第1引数 response の正体: { result: PointTransOpenResult } です。これは point_trans_preview の結果（total_price, use_point など）を包んだものであり、ポイント確定後の残高（total_point）や獲得ポイント（new_point）の確定値は含まれません。
• 確定値の取得経路:
  1. var result = await pointInstance.close() の戻り値（同一ページ）
  2. [point_trans_detail] ショートコードのコールバック（完了ページ）
  3. GET /wp-json/pointsystem/v1/point_trans_close/?orderId=...&customId=...（PSP検証済み）

5. トランザクション制御オブジェクト (point) の役割

point_trans_ready の第2引数として渡される point オブジェクトは、決済フローの中核です。モジュールレベル変数に保持し、後続処理で再利用してください。

6. 用語の正確な理解と実行順序の鉄則

本システムに「ポイントを仮確保してロックする」という中間状態は存在しません。用語と順序の誤解がポイント消失や二重利用の原因となります。

✅ 標準実行順序（use_point > 0 の場合）

1. point_trans_ready コールバック発火 → pointInstance を保持
2. ユーザーが「決済へ進む」をクリック
3. await pointInstance.close() を実行 → ポイントが確定控除される
4. PSPセッション作成 → Stripe/PayPalへリダイレクト
5. PSP成功: 完了ページで [point_trans_detail] 表示
6. PSP失敗/キャンセル: await pointInstance.cancel() を実行 → ポイントが復元される

💡 なぜ close() をPSP前に実行するのか？ リダイレクト型決済では、ページ離脱後に close() を呼ぶ手段がなくなります。また、PSP処理中に同一アカウントが別タブで未確定のポイントを別取引で使う余地（二重利用リスク）を排除するため、控除先行 → 失敗時ロールバックが唯一安全なパターンです。

7. 実装上の禁止事項・注意事項

以上でRewald（リワルド）が提供するショートコード（機能別コード）に関する解説は終了です。

最後にシステム全体に関わる制約やセキュリティ上の重要事項をまとめます。

7.0 重要事項

このセクションでは、Rewald（リワルド）により構築されたポイントシステムを運用する際の制約条件やセキュリティに関する注意点を解説します。必ず内容を確認し、規約と合わせて項目の詳細を遵守してください。

7.1. プランによる機能制限

無料プランの制限

無料プランをご利用の場合、以下の機能制限が適用されます。

月間決済金額の上限が JPY 100,000 までとなります。

利用可能な通貨は JPY のみです。

料率（conv_rate / use_rate）の指定はできません。

これらの制限を解除するには、有料プランへの移行が必要です。

7.2. セキュリティに関する注意

認証情報の管理
環境設定コードに含まれるACCESS_TOKENは、API認証に関わる極めて重要な機密情報です。ソースコード管理やサーバー設定において、この情報が外部に漏洩しないよう、厳重な管理体制を構築してください。また、デバッグログの出力やデータベースのエクスポートを行う際には、必ずACCESS_TOKENに対してマスク処理を施し、平文で記録が残らないようにしてください。

8.0 付録

8.1. よくある質問 (FAQ)

実装時によく発生する問題とその解決策をまとめました。

Q. WordPressでショートコードが動作しません

A. ご利用テーマの functions.php に、ショートコードを有効化するための実行関数が正しく記載されているか確認してください。

Q. 環境コードが読み込まれない

A. ブラウザのキャッシュが原因である可能性があります。ブラウザのキャッシュをクリアしてから、ページを再読み込みして動作を確認してください。

Q. PHP環境で関数が未定義エラー（Call to undefined function）になります

A. 環境設定コードが正しくグローバル変数定義箇所や共通の初期化ファイルで読み込まれているか確認してください。

Q. PHPテンプレート内でHTMLと混在させる場合の注意点はありますか？

A. <?php point_xxx(...) ?> の形式で、HTMLの任意の場所に記述可能です。出力結果が意図したHTML要素内に展開されるよう、適切な場所に配置してください。