Rewald（リワルド）ポイントシステム 技術仕様・実装ガイド
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. 環境設定コードの組み込み
環境設定コードの組み込み場所
取得した環境設定コードは、ウェブサイトやモバイルアプリ全体で読み込まれる場所に設置する必要があります。利用環境に応じて、以下の適切な場所にコードをコピー＆ペーストしてください。
| 利用環境 | 記載場所 |
|---|---|
| WordPress | ご利用テーマの functions.php |
| 独自のPHPプログラム | システムのグローバル変数定義箇所 |
警告： 認証情報の取り扱いについて
この環境設定コードには、ACCESS_TOKENを含む機密性の高い認証情報が含まれています。このコードブロック全体を秘密情報として扱い、ログ・エクスポート時の平文記録を避け、第三者への漏洩が決して発生しないよう厳重に管理してください。環境設定コードの組み込みが完了することで、具体的なポイント処理機能を実装するための基盤が整います。
3.0 Rewald（リワルド）が実現するポイント処理の基本的な考え方と実装手法
3.1. ポイント処理の全体像
個別のショートコード（機能別コード）を解説する前に、Rewald（リワルド）がどのようにポイント処理を実現しているか、その全体的な仕組みと設計指針を理解することが重要です。Rewald（リワルド）のポイント処理は、特定のユースケースに応じて設計された、以下の8つのショートコード（機能別コード）の組み合わせによって実現されます。
-
[point_setting] 基礎情報の設定 (通貨/料率などの定義)
-
[point_trans_open] 決済データと紐付け
-
[point_trans_close] ポイント処理完了フラグ
-
[point_trans_detail] 実行結果の通知
-
[point_trans_cancel] ポイント処理キャンセル時の通知
-
[point_own] 獲得済みポイント数の表示
-
[point_purchase_open] ポイントの購入処理開始
-
[point_purchase_close] 決済金額を確定した後、指定のポイント数を付与
3.2. 実装手法の比較
Rewald（リワルド）は利用環境に合わせて、以下の2つの記述方式を提供しています。
WordPress環境
記述方式: ショートコード形式 [...]
設置場所: 投稿・固定ページ、ウィジェット内など
独自開発サイト (PHPプログラム)
記述方式: PHP関数形式 <?php point_xxx(array(...))?>
設置場所: PHPテンプレートファイル内（HTMLとの混在可）
3.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（リワルド）とポイント情報を同期します。この実装よって、ログインさえすればデバイスを問わずポイント情報を永続的に保持できます。
これらの基本概念を理解した上で、次のセクションからは機能別に具体的なトランザクションの実装方法を解説します。
4.0 標準トランザクション実装（商品購入時のポイント利用）
Rewald（リワルド）のクライアントサイド処理は非同期で実行されます。そのため、システム全体を通してcallbackパターンが中心的な役割を果たします。各ショートコード（機能別コード）のcallback_name属性は、ポイント計算後の最終金額や処理結果といった非同期処理の結果を受け取り、サイト独自のJavaScriptロジック（例：決済代行会社のSDKへデータを渡す処理）と連携するための指定されたメカニズムです。このアーキテクチャを理解することが円滑な実装の鍵となります。
4.1. 実装フローの概要（機能別コード・詳細リファレンス）
このセクションでは、顧客が商品を購入する際にポイントを「利用」または「獲得」する場合の最も基本的な処理フローについて解説します。一連の処理は複数のショートコード（機能別コード）を適切なページに順を追って設置することで実現されます。
4.2. [point_setting] 基礎情報の設定
役割: ポイント処理を実行するにあたっての基礎情報を定義する。
解説: 処理の対象となる通貨と実行時の料率（還元と使用）を指定します。
設置場所: ポイント利用数を入力するフォームが存在するページに設置してください。
記述形式:
WP: [point_setting currency_type="JPY" conv_rate="5" use_rate="0.1"]
PHP: <?php point_setting(array('currency_type' => 'JPY', 'conv_rate' => '5', 'use_rate' => '0.1'))?>
【独自開発のPHPプログラム環境向け 補足仕様】
PHP関数形式: <?php point_setting(array('currency_type' => 'JPY', 'conv_rate' => '5', 'use_rate' => '0.1'))?>
※属性名は連想配列のキーとして指定します。
属性一覧:
| 属性名 | 設定値 | 説明 |
|---|---|---|
| currency_type | JPY, USD, EUR, BTC | 処理対象の通貨を指定します。※利用開始直後はJPYのみ有効。 |
| conv_rate | 0.1-100 (%) | 還元率（ポイント付与率）。適用後の発生金額の端数は四捨五入されます。 |
| use_rate | 0.1-100 (%) | 使用率（ポイント利用時の交換レート）。適用後の発生金額の端数は四捨五入されます。 |
| rate | 0.1-100 (%) | conv_rateとuse_rateの値が同じ場合に集約して指定できる代替属性です。 |
| callback_name | myFunctionName | 設定値の確認などが必要な場合に任意のJavaScript関数を呼び出します。 |
実装時の注意点:
料率の記述ルール: 料率の指定は個別属性（conv_rateおよびuse_rate）か集約属性（rate）のいずれか一方のみを使用してください。両方の形式を同一ショートコード内で混在させた場合、エラーが返されます。
機能制限: Rewald（リワルド）の利用開始直後は料率（conv_rate, use_rate）の指定はできません。
4.3. [point_trans_open] 決済データとの紐付け
役割: 決済金額の合計にポイント計算処理を追加する。
解説: 決済の最終確定金額を算出するための重要な役割を担います。callback_name属性で指定された関数には、ポイント利用額を差し引いた後の最終的な決済金額が渡され、この金額を決済代行業者と連携させます。
設置場所: ポイント利用数の入力欄と、決済金額の合計表示部分の両方が存在するページに設置してください。
記述形式:
WP: [point_trans_open var_price_id="ID" callback_name="myFunc"]
PHP: <?php point_trans_open(array('price' => 'ID', 'callback_name' => 'myFunc'))?>
【独自開発のPHPプログラム環境向け 補足仕様】
PHP関数形式: <?php point_trans_open(array('var_price_id' => 'ID', 'callback_name' => 'myFunc'))?>
※属性名は連想配列のキーとして指定します。
属性一覧:
| 属性名 | 設定値 | 説明 |
|---|---|---|
| var_price_id | string | Rewaldが計算に使用する合計金額の値を含むHTML要素のid属性を指定します。 |
| var_use_point_id | string | ポイント数を入力するinputタグのid属性を指定します。 |
| var_point_select_name | string | ポイント利用方法が選択式UIの場合に使用します。指定した値をinput type="radio"のname属性に設定し、各選択肢のvalue属性にno（利用しない）、var（一部利用）、all（すべて利用）を割り当てます。 |
| callback_name | myFunctionName | ポイント処理後の最終確定金額を受け取るための、独自のJavaScript関数を指定します。 |
実装時の注意点:
このショートコードは多くの場合[point_setting]タグと一対で注文確認画面に設置されます。
Rewald（リワルド）のポイント計算処理は「決済時の合計金額」に対してのみ適用される仕様です。ショッピングカート内の商品個別の価格に対して計算する設計にはなっておらず、常に合計金額を一つの単位として扱います。
4.4. [point_trans_close] ポイント処理完了
役割: 注文確定（決済）ボタンと連携し、一連のポイント処理トランザクションを確定・終了させる。
解説: callback_id属性で決済ボタンのHTML要素を特定し、ボタンクリックをトリガーとしてポイント処理の最終確定を実行します。同時にcallback_nameで指定された関数を通じて、最終確定金額を通知（取得）します。
設置場所: 注文確定（決済）ボタンが設置されるページに配置してください。
記述形式:
WP: [point_trans_close callback_id="button_id" callback_name="myFunc"]
PHP: <?php point_trans_close(array('callback_name' => 'myFunc'))?>
【独自開発のPHPプログラム環境向け 補足仕様】
PHP関数形式: <?php point_trans_close(array('callback_id' => 'button_id', 'callback_name' => 'myFunc'))?>
※属性名は連想配列のキーとして指定します。
属性一覧:
| 属性名 | 設定値 | 説明 |
|---|---|---|
| callback_id | string | 最終的な決済をトリガーするボタン要素のid属性を指定します。Rewald（リワルド）は、この要素のclickイベントにトランザクション完了ロジックをバインドします。 |
| callback_name | myFunctionName | ポイント処理終了後の最終確定金額を受け取るための、独自のJavaScript関数を指定します。 |
実装に関する補足: callback_nameで取得する最終確定金額は全額ポイント利用などで費用が発生しない「金額ゼロ」の場合における処理分岐に利用できます。例えば、決済金額が0円であれば決済ボタンを非表示にする、といった制御のトリガーとして用いることも可能だと思います。
4.5. [point_trans_detail] 実行結果の通知
役割: 実行されたポイント処理の詳細情報（利用ポイントや獲得ポイントなど）を取得・表示する。
解説: ポイント処理を実行した後に算出された最終確定金額も含め、詳細情報を通知します。
設置場所: 注文完了ページに設置してください。
記述形式:
WP: [point_trans_detail callback_name="myFunc"]
PHP: <?php point_trans_detail(array('callback_name' => 'myFunc'))?>
【独自開発のPHPプログラム環境向け 補足仕様】
PHP関数形式: <?php point_trans_detail(array('callback_name' => 'myFunc'))?>
※属性名は連想配列のキーとして指定します。
属性一覧:
| 属性名 | 設定値 | 説明 |
|---|---|---|
| callback_name | myFunctionName | 実行されたポイント処理の結果情報を受け取るためのJavaScript関数を指定します。 |
4.6. [point_trans_cancel] キャンセル処理
役割: ポイント関連処理をすべて取り消し、その結果を通知する。
解説: 何らかの理由により決済がキャンセルされた場合にポイント関連処理を強制的に取り消し、その旨の通知もおこないます。
設置場所: 注文キャンセルページなど、処理が取り消されたことをユーザーに通知するページに設置します。
記述形式:
WP: [point_trans_cancel callback_name="myFunc"]
PHP: <?php point_trans_cancel(array('callback_name' => 'myFunc'))?>
【独自開発のPHPプログラム環境向け 補足仕様】
PHP関数形式: <?php point_trans_cancel(array('callback_name' => 'myFunc'))?>
※属性名は連想配列のキーとして指定します。
属性一覧:
| 属性名 | 設定値 | 説明 |
|---|---|---|
| callback_name | myFunctionName | ポイント処理が取り消された結果情報を受け取るためのJavaScript関数を指定します。 |
以上が標準的なユースケースとして発生し得る商品購入時に対応するポイント処理の流れです。
次に特殊なトランザクションであるポイントそのものを購入する場合の処理について解説します。
5.0 ポイント購入のための処理実装
5.1. 実装の流れと技術的考察
ポイント購入の処理は商品購入時のポイント利用や獲得の流れとは異なり、決済の失敗やキャンセル時にポイントが不正に取得されるリスクを伴います。そのため、特に慎重な設計と思慮深い実装が求められます。
この処理の実装が技術的に難しい理由は以下の点にあります。
脆弱性の発生: 商品購入時には「先にポイントを確保してから決済する」という実装ロジックを実現してますが、この処理ロジックを踏襲すると決済がキャンセルされた場合にポイントだけが不正に取得される脆弱性が生まれます。
決済代行業者（PSP）への適合: 決済代行業者（PSP）の仕様、例えば費用が発生しない金額ゼロ決済時のハンドリングや決済額が確定した後に動的に決済ボタンが生成される仕様など、外部システムの要件に適合させながらRewald（リワルド）でポイント処理を実装する必要があります。
5.2. [point_purchase_open] ポイント購入処理の開始
役割: ポイント購入処理のトランザクションを開始して、指定された支払金額に対して付与されるポイント数を算出する。
解説: ポイントそのものを購入する為の処理に特化した機能別コードです。内部処理的には商品購入時のポイント消費と違い、最初に決済金額を取得した後、後続のポイント付与処理などを開始します。
設置場所: ポイント購入ができるページ
記述形式:
WP: [point_purchase_open conv_rate="100" callback_id="btn_id" callback_name="myFunc"]
PHP: <?php point_purchase_open(array('conv_rate' => '100', 'callback_name' => 'myFunc'))?>
【独自開発のPHPプログラム環境向け 補足仕様】
PHP関数形式: <?php point_purchase_open(array('conv_rate' => '100', 'callback_id' => 'btn_id', 'callback_name' => 'myFunc'))?>
※属性名は連想配列のキーとして指定します。
属性一覧:
| 属性名 | 設定値 | 説明 |
|---|---|---|
| currency_type | JPY, USD, EUR, BTC | 処理対象の通貨を指定します。※利用開始直後はJPYのみ有効。 |
| conv_rate | 100-XXX (%) | 還元率（ポイント付与率）を指定します。端数は四捨五入されます。 |
| callback_id | string | 決済（注文確定）ボタンに付与されたid属性を指定します。 |
| callback_name | myFunctionName | 決済ボタンに割り当てられた金額で購入できるポイント数を返すJavaScript関数を指定します。 |
実装時の注意点:
機能制限: 購入金額を選択式のUIで指定するような実装はサポートされていません。
料率仕様: 「conv_rate」は為替変動の影響を避けるため、等価率（100%）を基準とする固定換算方式を採用しています。
非対応ロジック: 保有ポイントを利用して新たなポイントを購入する、というユースケースは想定されておらず、現実事象としても無意味でもあるため実装できません。
5.3. [point_purchase_close] ポイント購入処理の完了
役割: 決済処理が完了した後、購入されたポイント数を正式に付与する処理を完了する。
解説: ポイント購入の為の決済金額を取得したあとの付与ポイント数を確定させて、最終的に購入者にポイント付与を実施します。
設置場所: ポイントの購入が正常に終了した事を知らせるページ（いわゆる決済完了ページ）
記述形式:
WP: [point_purchase_close callback_name="myFunc"]
PHP: <?php point_purchase_close(array('callback_name' => 'myFunc'))?>
【独自開発のPHPプログラム環境向け 補足仕様】
PHP関数形式: <?php point_purchase_close(array('callback_name' => 'myFunc'))?>
※属性名は連想配列のキーとして指定します。
属性一覧:
| 属性名 | 設定値 | 説明 |
|---|---|---|
| callback_name | myFunctionName | 最終的に購入されたポイント数と、その決済金額の情報を受け取るためのJavaScript関数を指定します。 |
ポイントそのものを購入するという特殊な処理の解説は以上になります。
次にサイトやモバイルアプリの様々な場所で利用できる汎用的なユーティリティ機能について解説します。
6.0 ユーティリティ機能
このセクションでは、主要なトランザクションフロー以外の補助的な処理を提供するショートコードについて解説します。
6.1. [point_own] 保有ポイント数の表示
役割: 対象者の現在保有しているポイント数を取得・表示する。
解説: ポイント保有者などに対して、これまでに獲得したポイント数を通知します。獲得ポイント数をお知らせする場合、そのための関数をコールバック（callback_name）で指定します
設置場所: 特定の制約はありません。利用者のマイページやヘッダーなど、任意の場所に設置可能です。
記述形式:
WP: [point_own callback_name="myFunc"]
PHP: <?php point_own(array('callback_name' => 'myFunc'))?>
【独自開発のPHPプログラム環境向け 補足仕様】
PHP関数形式: <?php point_own(array('callback_name' => 'myFunc'))?>
※属性名は連想配列のキーとして指定します。
属性一覧:
| 属性名 | 設定値 | 説明 |
|---|---|---|
| callback_name | myFunctionName | 取得した保有ポイント数を画面に表示・通知するための独自のJavaScript関数を指定します。 |
以上で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要素内に展開されるよう、適切な場所に配置してください。