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

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（リワルド）とポイント情報を同期します。この実装よって、ログインさえすればデバイスを問わずポイント情報を永続的に保持できます。

これらの基本概念を理解した上で、次のセクションからは機能別に具体的なトランザクションの実装方法を解説します。

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

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

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

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

2. [point_trans_open] 決済データと紐付け

3. [point_trans_close] ポイント処理完了フラグ

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)
• 引数構造:
  • response: 設定結果を含むオブジェクト（PointSystemResult<PointSettingResult>）。
  • response.error: エラー発生時のメッセージ（成功時は null または undefined）。
  • response.result: 初期化された設定情報。
    • session_token: セッション識別トークン。
    • currency_type: 通貨コード。
    • conv_rate: 適用された還元率。
    • use_rate: 適用された使用率。
• 用途: 設定が正しく反映されたことを確認したり、UI の初期表示を更新する際に使用します。

4.3. [point_trans_open] 決済データとの紐付け

役割: ユーザーが入力したポイント利用額に基づき、再計算された「最終決済金額」を算出し、通知します。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response)
• 引数構造:
  • response: 計算結果を含むオブジェクト（PointSystemResult<PointTransOpenResult>）。
  • response.result.total_price: ポイント利用額を差し引いた後の最終お支払い金額。
  • response.result.use_point: 今回利用されるポイント数。
  • response.result.price: 商品元の価格。
  • response.result.point: 現在の保有ポイント数。
  • response.result.pointsystem_nonce: このトランザクション固有の nonce トークン（後続処理で必須）。
• 注意: conv_point や grant_point といったプロパティはこの段階では返されません。これらは point.close() の戻り値に含まれます。
• 用途: 画面に表示されている「お支払い金額」を動的に更新したり、金額が 0 円になった場合に決済ボタンの表示/非表示を切り替えるロジックで使用します。入力値が変更されるたびに発火します。

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

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

⚠️ 重要: 名前とは異なり、このコールバックは「close が完了した瞬間」ではなく、「close を実行できる準備が整った瞬間」に発火します。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response, point)
• 第 1 引数 response:
  • 内容: { result: PointTransOpenResult }
  • 意味: これは close の結果ではありません。point_trans_open と同じ内容（計算済みの価格情報など）を包んだものです。
  • 含まれるプロパティ: total_price, use_point, price, pointsystem_nonce など。
  • 注意点: new_point（獲得ポイント）や total_point（取引後残高）はここには含まれません。
• 第 2 引数 point (PointInstance):
  • 意味: トランザクションを制御するためのオブジェクト实例。
  • 主要メソッド:
  • point.close(): Promise を返す。ポイントを確定（残高変動）させる。戻り値に PointTransCloseResult（new_point, total_point など）が含まれる。
  • point.cancel(): トランザクションを取り消し、確定済みのポイントを元に戻す（ロールバック）。
  • point.url: REST API のベース URL。
  • point.data: { token, pointsystem_nonce } を含むオブジェクト（キャンセル時に使用）。
  • point.pointsystem_nonce: 現在のトランザクション固有のノンセストークン。
• 用途:
  1. 決済ボタンクリック時に await point.close() を呼び出してポイントを確定させる。
  2. 決済失敗時に await point.cancel() を呼び出してポイントを復元する（ロールバック）。
• Close 結果の取得方法（3 パターン）:
  1. 同一ページ内: var result = await point.close() の戻り値を確認。
  2. 別ページ: [point_trans_detail] ショートコードを使用。
  3. PSP 検証付き: REST API GET /wp-json/pointsystem/v1/point_trans_close/?orderId=...&customId=... を使用。

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

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

【属性一覧】

【callback_name の詳細仕様】

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

4.6. [point_trans_cancel] キャンセル処理

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

【属性一覧】

【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] ポイント購入処理の開始

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

【属性一覧】

【callback_name の詳細仕様】

• モード A: 価格指定モード (price 属性あり)

  • シグネチャ: function(response)
  • 引数構造:
  • response.result.pointsystem_nonce: 購入用 nonce トークン。
  • response.result.price: 購入対象金額。
  • 用途: 通常、非表示の <span> 内に配置し、テキストコンテンツとして nonce を取得するために使用されます。
  • 注意: purchase_amount, grant_point, currency というプロパティ名は存在しません。

• モード B: ポーリングモード (callback_id 属性あり、価格未定)

  • シグネチャ: function(btnDataset, pointsystem_nonce, signature)
  • 引数:
    1. btnDataset: ボタンの data- 属性群（DOMStringMap オブジェクト）。
    2. pointsystem_nonce: 文字列。
    3. signature: 署名文字列（HMAC-SHA256）。
  • 用途: 動的に価格が決まる場合などに使用されます。システムはボタンの data-order-id と data-amount 属性を 100ms 間隔で監視し、変更があるたびに fresh な nonce と signature を取得してこのコールバックを発火させます。response オブジェクトは返されません。

5.3. [point_purchase_close] ポイント購入処理の完了

役割: ポイント購入の決済完了後、正式にポイントが付与された結果を受け取ります。 ※シナリオ D, E では、ショートコードの自動実行ではなく、JavaScript の fetch で REST API を直接呼び出す形式が推奨されています。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response)
• 引数構造:
  • response: 購入完了結果を含むオブジェクト（PointSystemResult<PointPurchaseCloseResult>）。
  • response.result.point: 付与後のポイント残高。
• 注意: transaction_id プロパティは現在の仕様では保証されていません。主に point プロパティを使用してください。
• 実装上の注意: API レスポンスもこの response 構造と同じ形式になります。シナリオ D/E の完了ページでは、ショートコードとして配置せず、fetch() で /wp-json/pointsystem/v1/point_purchase_close/ を POST 呼び出しし、そのレスポンスを処理してください。

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

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

6.0 ユーティリティ機能

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

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

役割: 現在保有しているポイント数を非同期的に取得し、通知します。

【属性一覧】

【callback_name の詳細仕様】

• シグネチャ: function(response)
• 引数構造:
  • response: 残高情報を含むオブジェクト（PointSystemResult<PointOwnResult>）。
  • response.result.point: 現在の保有ポイント数（数値）。
• 用途: ヘッダーやマイページなど、サイトの任意の場所でリアルタイムに残高を表示するために使用します。

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

これまでに解説した各ショートコードで定義されている属性値「callback_name」の取扱いには開発者が必ず遵守すべき共通ルールが存在します。

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

コールバック関数はグローバルスコープで定義する必要があります（例: window.myCallback = function(...) { ... } または <script> タグ内のトップレベルで定義）

2. レスポンス構造の統一

すべてのコールバックで返される response オブジェクトは、以下の統一ラッパー構造を持ちます。

• response.error: エラー文字列（null または undefined の場合は成功）。
• response.result: 成功時のデータオブジェクト。
• 重要: プロパティへのアクセスは常に response.result.xxx です。response.xxx や response.result.result.xxx としないでください。

3. 【最重要】point_trans_close の動作理解

• 名前の罠: point_trans_close の callback は「close が終わった後」に呼ばれるのではなく、「close を実行できる準備が整った（インスタンスが生成された）」瞬間に呼ばれます。
• 第 1 引数の内容: ここに渡される response は point_trans_open の結果（価格計算結果）であり、ポイント付与後の残高などは含まれていません。
• 実際の close 結果の取得: ポイント付与後の残高（new_point, total_point）を知りたい場合は、第 2 引数の point.close() メソッドを呼び出し、その戻り値（Promise の解決値）を確認するか、別のページで [point_trans_detail] を使用してください。

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

一部のショートコード（主に point_trans_close）では第 2 引数として point オブジェクトが渡されます。これは決済フローの中核です。

• point.close(): ポイントを確定させます。決済成功時に必ず呼び出してください。
• point.cancel(): 確定したトランザクションを取り消し、ポイントを戻します。「仮確保の解除」ではなく「確定の取消（ロールバック）」です。決済失敗時に必ず呼び出してください。

5. 用語の正確な理解

• 仮確保: このシステムには「ポイントを仮確保してロックする」という状態は存在しません。open は計算のみ、close は即座に確定です。
• ロールバック: cancel() は、一度確定したトランザクションを強制的に元に戻す処理です。ブラウザバックやネットワークエラー発生時にポイントの不整合を防ぐために必須となります。

以上で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要素内に展開されるよう、適切な場所に配置してください。