VibeFox Pesapal for WooCommerce — ヘルプ

要件

WordPress: 6.2 以降。

WooCommerce: 8.0 以降がインストールされ、有効になっている必要があります。これがない場合、プラグインは有効化できません。

PHP: 8.0 以降。

Currency: 注文の通貨は KES、UGX、TZS、ZMW、RWF、USD のいずれかである必要があります。他の通貨の場合、チェックアウトで決済方法が非表示になります。注文はその注文の通貨で請求され、プラグインは通貨換算を行いません。金額は主要通貨単位で送信され、通貨の精度に丸められます（UGX と RWF は小数なし）。

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

VibeFox license key: vibefox.net で購入します。一つのキーは一つのドメインで使用できます。

インストール

1. WordPress で Plugins > Add New > Upload Plugin を開き、プラグインの ZIP ファイルを選択し、Install Now をクリックします。FTP で wcp_pesapal_pay フォルダーを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。

3. 設定を開きます：WooCommerce > Settings > Payments > Pesapal > Manage。または、プラグイン一覧ページでプラグイン名の下にある Settings をクリックします。

4. ページ上部のライセンス欄に VibeFox ライセンスキーを入力し、Activate をクリックします。

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

6. 本番のコンシューマーキーとシークレットを入力し、Sandbox mode のチェックを外して保存すると、実際の決済を受け付けられます。

設定

すべての設定は一つのページにあります：WooCommerce > Settings > Payments > Pesapal。フィールドの上にはモードを示すバッジが表示され、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 はテストモードと表示されます。

決済通知（IPN）

この欄にはストアの通知 URL が表示されます。形式は https://your-site/wc-api/pesapal_pay/ です。URL は初回決済時に Pesapal に自動登録され、サンドボックスと本番、キーの組み合わせごとに個別に登録されるため、設定は不要です。初回決済後、この欄には Registered IPN ID: と Pesapal が返した ID が表示されます。それまでは Not registered yet for the current mode and keys. と表示されます。URL はインターネットからアクセス可能でなければならず、メンテナンスモード、ファイアウォール、パスワード保護でアクセスを遮断しないでください。

チェックアウト

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 加盟店ダッシュボードのコンシューマーシークレットです。サンドボックスモードが無効な場合に使用されます。

モードの切り替えやキーの変更時に、別のモードやキーのアクセストークンまたは通知 ID を再利用することはありません。あるモードで開始した決済は、モードの切り替え後も常にそのモードで確認されます。

詳細設定

Debug log: Log Pesapal requests and notifications は WooCommerce > Status > Logs に詳細を記録します。ソースは wcp_pesapal_pay です。エラーと警告は常に記録されます。キー、トークン、購入者データは記録されません。初期値：オフ。

Delete data: Delete the plugin settings and logs when the plugin is deleted。注文に保存された Pesapal データ（追跡 ID、メモ）は決済履歴であり、常に保持されます。プラグインの無効化では何も削除されません。初期値：オフ。

チェックアウト

購入者は決済方法（初期値は Pesapal (M-Pesa, Airtel Money, cards)）を選択して注文します。サンドボックスモードでは、チェックアウトブロックに Sandbox mode: no real money will be charged. と表示されます。プラグインは注文の請求先情報を使用し、注文の通貨で注文総額の Pesapal 決済リクエストを作成し、モード、金額、Pesapal 追跡 ID を含む注文メモを追加します。購入者は Pesapal の決済ページに移動し、M-Pesa、Airtel Money、MTN、カード、銀行など、Pesapal が提供する方法で支払います。

注文が支払い済みになるのは Pesapal の確認後だけです。Pesapal の通知と購入者の戻りには決済データも署名も含まれないため、プラグインはそれらを信用しません。それぞれについて、決済開始時のモードで、認証済みのサーバー間リクエストにより Pesapal に取引状況を問い合わせます。また、取引がこの注文に属すること、支払額と通貨が注文と一致することも確認します。

支払い後、購入者は注文受領ページに戻ります。モバイルマネー決済には少し時間がかかることがあります。まだ決済が確認されていない場合、ページには 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. と表示されます。後で Pesapal の通知によって注文が完了します。注文が保留中になった場合、ページには Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed. と表示されます。

購入者が Pesapal ページでキャンセルすると、Pay for order ページに戻り、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 の理由が表示されます。技術的な詳細は注文メモとログに記録されます。注文総額はゼロより大きい必要があります。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで利用できます。WooCommerce の高性能注文ストレージ（HPOS）に対応しています。

本プラグインには、チェックアウトページ自体の決済フォーム（購入者は必ず Pesapal ページで支払います）、保存済みカード、サブスクリプションや継続課金、通貨換算の機能はありません。

注文と返金

注文ステータス

Pending payment: 購入者は Pesapal に移動しましたが、まだ支払っていないか、Pesapal がまだ決済を確認していません。

Processing: Pesapal が決済の完了を報告し、金額と通貨が一致しています。注文メモには金額、決済方法、Pesapal 確認コード、追跡 ID が表示されます。注文の取引 ID は Pesapal 追跡 ID です。各決済は一回だけ適用されます。

On hold: 支払額または通貨が注文と異なる場合（メモは Pesapal amount/currency mismatch — held for review）、または支払い前にキャンセルされた注文への入金があった場合です。Pesapal ダッシュボードで決済を確認し、注文を完了するか、返金してください。

Failed: Pesapal が最新の決済試行の失敗を報告しています。メモには Pesapal の理由が記載されます。購入者が Pay for order ページで再試行し、それも失敗した場合、理由を含む別のメモが追加されます。古い試行の失敗では注文は変更されません。購入者は再度支払えます。

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

支払い済み注文への二度目の決済試行も完了した場合、注文は変更されません。Pesapal ダッシュボードで二度目の決済を返金するようメモが追加されます。キャンセル済みや返金済みの注文が自動的に再開されることはありません。

返金

プラグインは Pesapal に返金を送信しません。Pesapal ダッシュボードで返金し、その後 WooCommerce に返金を手動で記録してください。

ライセンスキー

本プラグインは vibefox.net の VibeFox ライセンスキーで動作します。ライセンス欄は WooCommerce > Settings > Payments > Pesapal の上部にあります。License key にキーを貼り付け、Activate をクリックします。この欄には、ライセンスの有効期限や貴店のドメインなどの状態が表示されます。Check now で状態を再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから vibefox.net アカウントを開けます。

一つのキーは一つのドメインで使用できます。サイトからキーを削除しても、そのドメイン枠は解放されません。vibefox.net アカウントで枠を解放してください。

有効なキーがない場合、チェックアウトで購入者に Pesapal は表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン済みのショップ管理者には、(unlicensed — visible to admins only) と表示された決済方法が引き続き見えるため、キー購入前に設定とテストを行えます。プラグイン一覧ページと WooCommerce ページにリマインダーが表示されます。既存の注文には影響しません。開始済みの決済は引き続き Pesapal の通知と購入者の戻りによって確認されます。

ライセンスの期限が切れてもプラグインは動作し続けますが、更新とサポートには更新手続きが必要です。状態はバックグラウンドで自動的に再確認されます。

トラブルシューティング

チェックアウトに Pesapal が表示されない：ライセンスが有効で、Enable/Disable がオンになっており、現在のモードのコンシューマーキーとシークレットが入力されていること（サンドボックスでは Sandbox consumer key と Sandbox consumer secret、本番では Live consumer key と Live consumer secret）、注文の通貨が KES、UGX、TZS、ZMW、RWF、USD のいずれかであることを確認してください。設定上部の警告に問題が示されます。開発者は pesapal_p_supported_currencies フィルターで通貨一覧を変更できます。

決済は成功したが、注文が支払い待ちのまま：Pesapal の通知がストアに届かず、購入者も戻っていません。Payment notifications (IPN) に表示される URL がインターネットからアクセス可能か確認してください（/wc-api/pesapal_pay/ の前にメンテナンスモード、ファイアウォール、パスワード保護がないこと）。WooCommerce > Status > Logs でソース wcp_pesapal_pay を確認してください。

ストアによる通知への応答：処理済みの通知には 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 ダッシュボードで決済を確認し、注文を処理するか、返金してください。

ライセンス欄にエラーが表示される：欄内のメッセージに従ってください。たとえば、キーが別のドメインで使用中の場合、vibefox.net アカウントで枠を解放し、Check now をクリックします。サイトアドレスが変更された場合、Check now をクリックして新しいドメインでキーを有効化します。ライセンスサーバーに接続できない場合、プラグインは最後に確認できた状態で動作を続けます。

アンインストール

プラグインを無効化してもすべてのデータが保持されます。削除するには、Plugins ページで無効化して削除します。このプラグインのライセンスキーとライセンス状態、キャッシュされた Pesapal アクセストークン、登録済み通知 ID は必ず削除されます。プラグインの設定とログ（ローテーション済みファイルを含むログファイルと、ソース wcp_pesapal_pay のデータベース内ログエントリー）は、Delete data がオンだった場合にのみ削除されます。それ以外は後の再インストール用に保持されます。既存の注文は決済メモ、取引 ID、Pesapal 追跡 ID を保持します。

Pesapal は、それぞれの所有者の商標です。本プラグインは Pesapal と提携しておらず、Pesapal の承認も受けていません。