VibeFox Pesapal for PrestaShop — ヘルプ

要件

PrestaShop：8.0～9.x。

PHP：8.0 以降。古いバージョンの PHP ではモジュールをインストールできません。

通貨：カートは KES、UGX、TZS、ZMW、RWF、USD のいずれかである必要があります。それ以外の通貨の場合、チェックアウトで決済方法は表示されません。カートはその通貨で請求され、モジュールは通貨換算を行いません。金額は主要単位で送信され、通貨の精度に合わせて丸められます（UGX と RWF は小数点以下の桁がありません）。

Pesapal アカウント：Pesapal 加盟店アカウントのコンシューマーキーとコンシューマーシークレットが必要です。サンドボックス用と本番用のキーは別々です。サンドボックスのキーは cybqa.pesapal.com のデモ加盟店アカウントから取得します（Pesapal は開発者ポータルでもデモ用キーを公開しています）。本番用のキーは Pesapal の加盟店ダッシュボードから取得します。Pesapal のダッシュボードで他に設定する必要はありません。モジュールが通知 URL を自動で登録します。Pesapal は決済通知を貴店のショップに送信するため、ショップがインターネットからアクセス可能である必要があります。

VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。

インストール

1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

2. アップロードが完了したら、Configure をクリックします。後で設定する場合は、モジュール一覧から VibeFox Pesapal Pay Gateway を探し、Configure をクリックします。

3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。

4. サンドボックスのコンシューマーキーとコンシューマーシークレットを入力し、Enable/Disable を有効にして Save をクリックし、テスト注文を行います。

5. 本番のコンシューマーキーとコンシューマーシークレットを入力し、Sandbox mode を無効にして Save をクリックすると、実際の決済を受け付けられます。

インストール時に、モジュールは注文ステータス Pesapal payment on hold を作成します。PrestaShop は、新しい決済モジュールをすべての通貨、国、顧客グループで有効にします。Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。フィールドの上にあるバッジにモードが表示されます：SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. または LIVE — Real payments on pay.pesapal.com. 現在のモードのキーが未入力の場合（Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout.、または本番用の同様の文言）、および Pesapal がショップの既定通貨に対応していない場合には、警告が表示されます。

Pesapal

Enable/Disable：Enable Pesapal で決済方法を有効または無効にします。デフォルト：無効。

Title：チェックアウト時にお客様に表示される決済方法の名称です。注文にも決済方法名として保存されます。デフォルト：Pesapal (M-Pesa, Airtel Money, cards)。必須項目です。空のタイトルは保存されず、以前のタイトルが維持されます。

Description：チェックアウト時に決済方法の下に表示されるテキストです。デフォルト：Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

API 認証情報

このセクションでは、キーの取得方法を説明し、cybqa.pesapal.com と pesapal.com へのリンクを掲載しています。サンドボックスと本番のキーは、それぞれ別々のフィールドに入力してください。

Sandbox mode：Use the Pesapal sandbox (no real money)。有効にすると、新しい決済はサンドボックスのキーを使用して cybqa.pesapal.com で処理されます。実際の決済を本番のキーで pay.pesapal.com 上で受け付けるには、無効にしてください。デフォルト：有効。

Sandbox consumer key：サンドボックス（デモ）加盟店アカウントのコンシューマーキーです。サンドボックスモードでのみ使用されます。

Sandbox consumer secret：サンドボックス加盟店アカウントのコンシューマーシークレットです。サンドボックスモードでのみ使用されます。

Live consumer key：Pesapal の加盟店ダッシュボードにあるコンシューマーキーです。サンドボックスモードが無効のときに使用されます。

Live consumer secret：Pesapal の加盟店ダッシュボードにあるコンシューマーシークレットです。サンドボックスモードが無効のときに使用されます。

保存済みのキーとシークレットは、再度表示されることはありません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved consumer keys and secrets：チェックボックスをオンにして Save をクリックすると、保存済みの 4 つのキーとシークレットがすべて削除されます。

設定を保存すると、キャッシュされた Pesapal のアクセストークンは破棄されます。モードやキーを切り替えても、別のモードやキーのアクセストークンや通知 ID が再利用されることはありません。あるモードで開始された決済は、切り替えた後でも常に同じモードで確認されます。

決済通知（IPN）

IPN URL：貴店の通知 URL が表示されます。フレンドリー URL を使用している場合、https://your-shop/module/wcp_pesapal_pay/webhook のような形になり、/en/ などの言語コードが付くこともあります。この URL は最初の決済時に、サンドボックスと本番のそれぞれについて、またキーの組ごとに Pesapal へ自動的に登録されるため、設定は不要です。最初の決済の後、このセクションには Registered IPN ID: と、Pesapal から返された ID が表示されます。それ以前は Not registered yet for the current mode and keys. と表示されます。この URL はインターネットからアクセスできる必要があります。前段にファイアウォールやパスワード保護を設けないでください。ショップがメンテナンスモードでも動作し続け、貴店の国別制限の影響は受けません。

詳細設定

Debug log：Log Pesapal requests and notifications。詳細はモジュールのフォルダ内の logs/pesapal_p_debug.log.php に書き込まれます。このファイルは Web からは開けません。エラーと警告はスイッチがオフでも常に記録されます。キー、トークン、お客様データは記録されません。デフォルト：無効。

Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを消去できます。

Delete data：Delete the module settings and logs when the module is uninstalled。注文に保存された Pesapal のデータ（トラッキング ID、メモ）は決済履歴であり、常に保持されます。モジュールを無効にしても、何も削除されません。デフォルト：無効。

チェックアウト

決済ステップで、お客様は決済方法（デフォルトは Pesapal (M-Pesa, Airtel Money, cards)）を選択し、その説明を確認します。確定すると、モジュールはカートの合計金額をカートの通貨で対象とする Pesapal の決済リクエストを作成します。請求書住所の請求情報も含まれます。その後、お客様は Pesapal の決済ページへ移動します。Pesapal に送信される決済の説明は Cart、カート番号、ショップ名です。お客様はそのページで、M-Pesa、Airtel Money、MTN、カード、銀行振込など、Pesapal が提供する方法のいずれかで支払います。この時点では、まだ注文は存在しません。

注文は、Pesapal が決済を確認した後にのみ支払い済みになります。Pesapal からの通知とお客様の戻り操作には決済データも署名も含まれないため、モジュールはそれらを信頼しません。各通知または戻り操作のたびに、決済が開始されたモードで、認証されたサーバー間リクエストによって Pesapal に取引状況を問い合わせます。さらに、その取引がこのカートに属しているか、支払われた金額と通貨がカートと一致しているかを確認します。その後、注文が作成され、お客様には標準の注文確認ページが表示されます。

モバイルマネーによる決済は、確認に少し時間がかかる場合があります。お客様が戻った時点で Pesapal がまだ決済を確認していない場合、Payment confirmation ページに Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. と表示され、Check again と Back to checkout のボタンが表示されます。Pesapal からの通知により、決済が確認されるとすぐに注文が作成されます。注文が保留にされた場合、確認ページには Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed. と表示されます。

お客様が Pesapal のページでキャンセルすると、チェックアウトに戻り、The Pesapal payment was cancelled. You can try again or choose another payment method. と表示されます。決済に失敗した場合のメッセージは The Pesapal payment was not successful. Please try again or choose another payment method. です。カートは保持され、お客様は再度支払うことができます。カートのすべての決済試行は記録されるため、同じカートの古い Pesapal ページで後から行われた決済も受け付けられます。

Pesapal が決済を開始できない場合、お客様は短いメッセージとともにチェックアウトに留まります。たとえば、Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method.、Pesapal is not available at the moment. Please choose another payment method.（キーが誤っている場合）、または Pesapal could not start the payment: に続けて Pesapal からの理由が表示されます。技術的な理由はログに記録されます。注文の合計金額はゼロより大きい必要があります。

本モジュールには、貴店サイト上の決済フォームはありません（お客様は常に Pesapal のページで支払います）。また、保存済みカード、サブスクリプションや定期決済、通貨換算の機能もありません。

注文と返金

注文ステータス

まだ注文はありません：お客様は Pesapal に移動しましたが、まだ支払っていない、決済が失敗した、または Pesapal がまだ決済を確認していない状態です。カートだけが存在します。

Payment accepted：Pesapal が決済を完了として報告し、金額と通貨が一致している状態です。決済は Pesapal のトラッキング ID を取引 ID として記録され、メモには金額、決済方法、Pesapal の確認コード、トラッキング ID が表示されます。各決済は 1 回だけ適用されます。

Pesapal payment on hold：支払われた金額または通貨がカートと異なる（メモ：Pesapal amount/currency mismatch — held for review）場合、またはキャンセル済みの注文に対して入金があった場合です。実際に支払われた金額が注文の通貨である場合、注文に記録されます。Pesapal のダッシュボードで決済を確認し、その後で注文を完了するか、決済を返金してください。

Refunded：Pesapal が、注文の支払いに使用された決済が取り消されたと報告した状態です。別の試行の取り消しは、注文にメモとして記録されるだけです。

すでに支払い済みのカートに対する 2 回目の決済試行も完了した場合、注文は変更されません。メモには、Pesapal のダッシュボードで 2 回目の決済を返金するよう記載されます。キャンセル済みおよび返金済みの注文は、自動的に再び開かれることはありません。

Pesapal 決済ブロック

注文ページには、Sandbox または Live のバッジを付けた Pesapal payment ブロックが表示されます。このブロックには、トラッキング ID、加盟店参照番号、Pesapal ステータス、決済方法、確認コード、請求金額と支払金額、レビューの理由、カートのすべての Payment attempts、注文の Payment notes が含まれます。このブロックは読み取り専用です。

返金

本モジュールは Pesapal に返金を送信しません。Pesapal のダッシュボードで決済を返金し、その後 PrestaShop で返金を手動で記録してください。

ライセンスキー

本モジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Pesapal Pay Gateway は、Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure のページで設定より上にある最初のブロックです。License key にキーを入力し、Activate をクリックしてください。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日や貴店のドメインなど）と、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-payment-pesapal の行と、Manage licenses and domains in your account のリンク（vibefox.net のアカウントを開きます）があります。キーを変更できるのは、このモジュールの Configure 権限を持つ従業員だけです。ブロックの文言は管理画面の言語に従います（英語とロシア語が含まれます）。

キーが受け付けられない場合、ブロックに理由が表示されます。例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ショップのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスで動作を続けます。

1 つのキーは 1 つのドメインで使用できます。マルチストア構成の場合も、メインショップのドメインが対象です。ショップからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウトでお客様に Pesapal は表示されません。決済が開始された場合、お客様には This payment method is not available. Please choose another one. と表示されます。PrestaShop のフロントエンドは、管理画面にログインしていることを認識しないため、決済方法はご自身にも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響ありません。すでに開始された決済は引き続き確認され、既存の決済に関する Pesapal の通知（取り消しを含む）も引き続き適用されます。

ライセンスの有効期限が切れた後も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面での作業中に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは必ず削除されます。

トラブルシューティング

チェックアウトに Pesapal が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードのコンシューマーキーとコンシューマーシークレットが入力されていること（サンドボックスモードでは Sandbox consumer key と Sandbox consumer secret、本番モードでは Live consumer key と Live consumer secret）、そしてカートの通貨が KES、UGX、TZS、ZMW、RWF、USD のいずれかであることを確認してください。設定の上部に表示される警告に問題の内容が示されています。Payment > Preferences で、モジュールがカートの通貨、お客様の国、お客様のグループに対して許可されているか確認してください。開発者は、フック actionPesapalSupportedCurrencies を使用して通貨の一覧を変更できます。

決済は完了したが、注文が作成されない：Pesapal からの通知が貴店のショップに届かず、お客様も戻ってこなかった状態です。IPN URL に表示される URL がインターネットからアクセス可能であることを確認してください（前段にファイアウォールやパスワード保護がないこと）。Debug log をオンにし、モジュールのページにある Log フィールドを確認してください。

ショップが通知に応答する方法：処理された通知には HTTP 200 で応答します。モジュールが処理できない場合はエラーで応答し、Pesapal は後で通知を再送します。400（トラッキング ID がない、または形式が不正）、404（このショップのどのカートもそのトラッキング ID を持たない）、409（取引は別の加盟店参照番号に属している。何も変更されない）、502（その時点で Pesapal API に接続できない、または決済を開始したモードのキーがない）、503（お客様の戻り操作によってカートが同時に更新されていた、または注文を作成できなかった。たとえばモジュールが無効になっている場合）です。

お客様に Pesapal is not available at the moment と表示される：Pesapal が現在のモードのコンシューマーキーまたはシークレットを拒否しました。キーがモードと一致しているか確認してください。サンドボックスのキーはサンドボックスでのみ、本番のキーは本番モードでのみ機能します。ログには Pesapal のエラーが表示されます。

お客様に Pesapal is temporarily unavailable と表示される：Pesapal に接続できなかったか、通知 URL を登録できませんでした。ログを確認して、もう一度お試しください。

切り替え後、以前のモードの決済が確認されない：決済は、開始されたモードのキーを使用して確認されます。そのモードの決済が確認されるまで、そのモードのキーを入力したままにしてください。

決済後に注文が Pesapal payment on hold になっている：Pesapal payment ブロックのメモを確認してください。支払われた金額または通貨がカートと異なっていたか、注文のキャンセル後に決済が届いた可能性があります。Pesapal のダッシュボードで決済を確認し、その後で注文を処理するか、決済を返金してください。

アンインストール

Modules > Module Manager に移動し、VibeFox Pesapal Pay Gateway の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは、常に削除されます。キャッシュされた Pesapal のアクセストークンと登録済みの通知 ID は、常に削除されます。Delete data がオンの場合は、モジュールの設定とログも削除されます。オフの場合は、後で再インストールできるようにすべての設定が保持されます。Pesapal の決済試行と注文ステータス Pesapal payment on hold は、常に保持されます。既存の注文は、決済メモ、取引 ID、Pesapal のトラッキング ID を保持します。

Pesapal は、それぞれの所有者の商標です。本モジュールは Pesapal と提携しておらず、Pesapal による承認も受けていません。