VibeFox Pesapal for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 でテスト済み）、または 4.0.2 以降（4.1.0.3 でテスト済み）。
PHP: 8.0 以降。
通貨: 注文は KES、UGX、TZS、ZMW、RWF、USD のいずれかである必要があります。それ以外の通貨では、チェックアウト時に決済方法が表示されません。注文は元の通貨で請求されます。拡張機能は通貨換算を行いません。金額は主要単位で送信され、通貨の精度に合わせて丸められます（UGX と RWF は小数点なし）。
Pesapal アカウント: Pesapal 加盟店アカウントの consumer key と consumer secret が必要です。サンドボックスのキーと本番のキーは別物です。サンドボックスのキーは cybqa.pesapal.com のデモ加盟店アカウントから取得します（Pesapal は開発者ポータルでもデモキーを公開しています）。本番のキーは Pesapal の加盟店ダッシュボードから取得します。Pesapal ダッシュボードで他に設定する必要はありません。拡張機能が通知 URL を自動で登録します。Pesapal が決済通知を送信するため、ストアはインターネットからアクセスできる必要があります。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。内容は README.txt、OpenCart 3 用のパッケージ wcp_pesapal_pay-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ wcp_pesapal_pay.ocmod.zip です。お使いの OpenCart のバージョンのパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_pesapal_pay-oc3-(version).ocmod.zip を選択します。この拡張機能には OCMOD の変更がないため、Extensions > Modifications の更新は不要です。インストーラーを使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、種類 Payments を選択します。VibeFox Pesapal Pay Gateway を見つけて、Install（緑色の + ボタン）をクリックします。管理者ユーザーに、決済拡張機能の一覧を変更する権限が必要です。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（License key を参照）。
4. サンドボックスの consumer key と consumer secret を入力し、Enable/Disable を有効にして、Save をクリックし、テスト注文を行います。
5. 本番の consumer key と consumer secret を入力し、Sandbox mode を無効にして、Save をクリックすると、実際の決済を受け付けられます。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_pesapal_pay.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。
2. インストール済み拡張機能の一覧に、同じページでパッケージが表示されます。その横の Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox Pesapal Pay Gateway を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆ボタン）をクリックします。
4. OpenCart 3 の手順 3 から 5 と同じように、ライセンスキーと Pesapal のキーを入力します。設定ページとその欄は両方のバージョンで同じです。違うのは IPN URL だけです（「決済通知」を参照）。
新規インストールでは、決済方法は無効、サンドボックスモードは有効の状態で始まります。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit。セクションは左側に一覧表示されます。一覧の下にある Save ボタンでページ全体を保存します。設定の上にはモードを示すバッジが表示されます：SANDBOX — cybqa.pesapal.com でのテスト決済 — 実際の金額は請求されません。 または LIVE — pay.pesapal.com での実際の決済。 現在のモードのキーが未入力の場合（Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout.、または本番用の同じ表示）や、ストアの既定通貨を Pesapal がサポートしていない場合には警告が表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。
保存時に Title が空の場合は受け付けられません。以前のタイトルが保持され、エラーが表示されますが、その他のフィールドは保存されます。Sort Order は整数である必要があります（負の値も可）。Total は 0 以上の数値で、Geo Zone と注文ステータスは存在している必要があります。そうでない場合、そのフィールドは以前の値を保持し、エラーが表示されます。保存時には、キャッシュされた Pesapal のアクセストークンが破棄されます。
Pesapal
Enable/Disable: Enable Pesapal で決済方法の有効／無効を切り替えます。既定値: 無効。
Title: チェックアウトで購入者に表示される決済方法の名前です。注文にも決済方法名としてこの名前が保存されます。既定値: Pesapal (M-Pesa, Airtel Money, cards)。必須、最大 128 文字。
Description: Confirm Order ステップで、確認ボタンの上に購入者に表示されるテキストです。既定値: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.
Sort Order: チェックアウトの決済方法の中で Pesapal が表示される位置です。空欄のままにするか、整数を入力します。
Geo Zone: 選択したジオゾーン内の支払い先住所に対してのみ Pesapal を提供します。既定値: All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。
Total: Pesapal を提供するために注文が到達している必要がある、ストアの既定通貨でのチェックアウト合計金額です。空欄にすると、どの金額でも Pesapal を提供します。
API 認証情報
このセクションでは、キーの取得方法を説明し、cybqa.pesapal.com と pesapal.com へのリンクを掲載しています。サンドボックスのキーと本番のキーは、それぞれ専用のフィールドに入力してください。
Sandbox mode: Use the Pesapal sandbox (no real money)。有効にすると、新しい決済はサンドボックスのキーを使って cybqa.pesapal.com で処理されます。無効にすると、本番のキーを使って pay.pesapal.com で実際の決済を受け付けます。既定値: 有効。
Sandbox consumer key: サンドボックス（デモ）加盟店アカウントの consumer key です。サンドボックスモードでのみ使用されます。
Sandbox consumer secret: サンドボックス加盟店アカウントの consumer secret です。サンドボックスモードでのみ使用されます。
Live consumer key: Pesapal 加盟店ダッシュボードの consumer key です。サンドボックスモードが無効のときに使用されます。
Live consumer secret: Pesapal 加盟店ダッシュボードの consumer secret です。サンドボックスモードが無効のときに使用されます。
保存済みのキーとシークレットは二度と表示されません。フィールドは空のままで、保存済み — 変更しない場合は空欄のままにしてください。 と表示されます。変更したい場合にのみ新しい値を入力してください。
Clear saved consumer keys and secrets: キーが保存されているときに表示されます。チェックボックスをオンにして Save をクリックすると、保存されている 4 つのキーとシークレットがすべて削除されます。
モードやキーを切り替えても、もう一方のモードやキーのアクセストークンや通知 ID が再利用されることはありません。あるモードで開始された決済は、切り替え後も必ずそのモードで照合されます。
注文ステータス
OpenCart は Confirm Order ステップで、ステータスなしの注文（欠落注文）を作成します。注文にステータスが付くのは、Pesapal が決済を「Completed」として報告した後だけです。以下の各フィールドには、OpenCart の注文ステータスが一覧表示されます。
Order Status After Payment: Pesapal が決済を確認したときに設定されるステータスです。既定値: Processing。
Pesapal Payment On Hold Status: 金額または通貨が注文と一致しない決済、およびキャンセル後に届いた決済です。メモに理由が記録されます。既定値: Pending（OpenCart には On hold ステータスがないため）。独自のステータスは System > Localisation > Order Statuses で作成し、ここで選択できます。
Cancelled Order Status: このステータス（または返金済みステータス）の注文に対して Pesapal の決済が届いた場合、注文は黙って再開されるのではなく保留になります。既定値: Canceled。
Refunded Status: Pesapal が注文の決済を取り消されたと報告したときに設定されます。既定値: Refunded。
決済通知（IPN）
IPN URL: ストアの通知 URL を表示します。OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_pesapal_pay/ipn の形式で、OpenCart 4 では https://your-store/index.php?route=extension/wcp_pesapal_pay/payment/wcp_pesapal_pay.ipn の形式です。URL はOpenCart インストールのストアフロントのアドレスから生成されます。この URL は最初の決済時に Pesapal へ自動的に登録されます。サンドボックスと本番、そして各 consumer key ごとに個別に登録されるため、設定すべきことはありません。最初の決済の後、このセクションには Pesapal から返された ID とともに Registered IPN ID: が表示されます。それまでは 現在のモードとキーではまだ登録されていません。 と表示されます。この URL はインターネットからアクセスできる必要があります。前にファイアウォールやパスワード保護を置かないでください。ストアがメンテナンスモードでも動作し続けます。OpenCart は決済拡張機能のリクエストを通過させるためです。OpenCart 4 では、拡張機能が独自の起動アクションを追加しており、これにより購入者は Pesapal から戻ることもできます。
詳細設定
Debug log: Pesapal のリクエストと通知を、OpenCart のログフォルダ（storage/logs）にある pesapal_p_debug.log.php に記録します。このファイルは Web から開くことができず、5 MB に達すると pesapal_p_debug.old.log.php に移動されます。エラーと警告は、スイッチがオフでも常に記録されます。キー、トークン、顧客データは記録されません。既定値: 無効。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。
Delete data: 拡張機能のアンインストール時に、拡張機能の設定とログを削除します。注文に保存された Pesapal のデータ（追跡 ID、メモ）は決済履歴であり、常に保持されます。拡張機能を無効にしても、何も削除されません。既定値: 無効。
インポート / エクスポート
Export: Download JSON で、設定を JSON ファイルとして保存します。consumer key と consumer secret はエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みの consumer key と consumer secret は保持されます。
チェックアウト
Payment Method ステップで、購入者は決済方法を選択します（既定では Pesapal (M-Pesa, Airtel Money, cards)）。Confirm Order ステップでは、購入者にあなたの説明文が表示されます。OpenCart はこのステップで、まだステータスのない注文を作成します。OpenCart 4 では、購入者は決済方法ブロックの Choose ボタンを押し、Payment method options ウィンドウで決済方法を選んで、チェックアウトページ下部の Confirm Order をクリックします。購入者が Confirm Order をクリックすると、拡張機能は注文の通貨で注文合計額に対する Pesapal の決済リクエストを作成し、支払い先住所の請求情報（OpenCart 4 では、チェックアウトが支払い先住所を求めない場合は配送先住所の情報）を添えて、購入者を Pesapal の決済ページへ移動させます。Pesapal に送信される決済の説明は Order、注文番号、ストア名です。購入者はそこで、M-Pesa、Airtel Money、MTN、カード、銀行など、Pesapal が提供する方法のいずれかで支払います。注文のメモには、決済リクエストが記録されます。
注文が支払い済みとしてマークされるのは、Pesapal が確認した後だけです。Pesapal の通知と購入者の戻りには決済データも署名も含まれていないため、拡張機能はそれらを信頼しません。通知や戻りのたびに、拡張機能は決済が開始されたモードで、認証されたサーバー間リクエストにより Pesapal に取引状況を問い合わせます。さらに、その取引がこの注文のものであること、支払われた金額と通貨が注文と一致することを確認します。その後、注文は通常の OpenCart の方法でステータスを受け取り、通常の注文メールと在庫の更新が行われ、購入者には OpenCart の注文完了ページが表示されます。
モバイルマネー決済には少し時間がかかる場合があります。購入者が戻った時点で Pesapal がまだ決済を確認していない場合、Payment confirmation ページに お支払いは Pesapal で確認中です。確認が完了するとメールでお知らせします — 再度お支払いいただく必要はありません。 と表示され、Check again と Back to checkout のボタンが表示されます。Pesapal からの通知は、決済が確認されるとすぐに注文ステータスを設定します。注文が保留された場合、完了ページには お支払いは受領され、ストアで確認中です。注文が確定すると、メールでお知らせします。 と表示されます。後の決済によって注文が保留ステータスから支払い済みステータスに移ると、購入者にメールで通知されます。
購入者が Pesapal のページでキャンセルした場合、チェックアウトに戻り、Pesapal の決済はキャンセルされました。もう一度お試しいただくか、別の決済方法をお選びください。 と表示されます。決済に失敗した場合は、Pesapal の決済は成功しませんでした。もう一度お試しいただくか、別の決済方法をお選びください。 と表示され、注文のメモに理由が記録されます。カートは保持され、購入者は再度支払うことができます。OpenCart 4 では、これらのメッセージはチェックアウトページの上に表示されます。OpenCart 3 は Confirm Order ステップが表示されるたびに新しい注文を作成し、OpenCart 4 はチェックアウトの注文を更新するため、新しい決済を行う前に、拡張機能はカートの以前の決済の試行を Pesapal で確認します。そのいずれかがその間に支払われていれば、その注文がステータスを受け取り、購入者は二重に支払うことなく完了ページへ進みます。カートの古い Pesapal ページで後から行われた決済も、引き続き受け付けられます。カートを変更した場合（数量の変更を含む）は、新しいカートとして扱われ、独自の決済が必要です。
OpenCart 4 では、完了ページが表示されるまで注文がチェックアウト内に保持されます。その間に注文が閉じられた場合（たとえばキャンセルした場合）、または以前のカートについて支払い済みで、その後カートが変更された場合、購入者は Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. というメッセージとともにチェックアウトに戻されます。次の Confirm Order で新しい注文の決済が行われます。閉じられた注文が支払い済みとして表示されることはありません。
Pesapal が決済を開始できない場合、購入者は Confirm Order ステップにとどまり、ボタンの上に短いメッセージが表示されます。例: Pesapal は一時的に利用できません。数分後にもう一度お試しいただくか、別の決済方法をお選びください。、Pesapal は現在利用できません。別の決済方法をお選びください。（キーが誤っている場合）、または Pesapal で決済を開始できませんでした: に続けて Pesapal が示した理由が表示されます。技術的な理由はログと注文メモに記録されます。注文合計額は 0 より大きい必要があります。
この拡張機能には、ご自身のサイト上の決済フォームはありません（購入者は必ず Pesapal のページで支払います）。保存済みカード、サブスクリプションや定期決済、通貨換算もサポートしていません。
注文と返金
注文ステータス
ステータスなし（欠落注文）: 購入者は Pesapal に移動したものの、支払っていない、決済が失敗した、または Pesapal がまだ決済を確認していない状態です。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。
Order Status After Payment（既定値 Processing）: Pesapal が決済を Completed として報告し、金額と通貨が一致した状態です。メモには、金額、決済方法、Pesapal の確認コード、追跡 ID が表示されます。各決済は 1 回だけ適用されます。
Pesapal Payment On Hold Status（既定値 Pending）: 支払われた金額または通貨が注文と異なる（メモ Pesapal amount/currency mismatch — held for review）、またはキャンセル済みまたは返金済みステータスの注文に対して入金があった状態です。Pesapal ダッシュボードで決済を確認してから、注文を完了するか決済を返金してください。
Refunded Status（既定値 Refunded）: Pesapal が、注文を支払った決済が取り消されたと報告した状態です。別の試行の取り消しは、注文にメモとして記録されるだけです。
すでに支払い済みの注文またはカートに対して 2 回目の決済も完了した場合、その注文は変更されません。支払い済みの注文のメモには、Pesapal ダッシュボードで 2 回目の決済を返金するよう記載されます。キャンセル済みおよび返金済みの注文が自動的に再開されることはありません。
メモは注文の History に記録されるエントリで、購入者には表示されません。
VibeFox Pesapal Pay Gateway tab
Sales > Orders で、Pesapal で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox Pesapal Pay Gateway タブには、Sandbox または Live のラベル付きの追跡 ID、加盟店参照番号、Pesapal のステータス、決済方法、確認コード、要求された金額と支払われた金額、審査の理由、注文のすべての Payment attempts（複数ある場合）、Payment notes が表示されます。このタブは読み取り専用で、拡張機能へのアクセス権を持つユーザーに表示されます。
返金
拡張機能は Pesapal に返金を送信しません。Pesapal ダッシュボードで決済を返金し、その後 OpenCart に返金を手動で記録してください。Sales > Returns での商品返品では、Pesapal を通じて代金が返金されることはありません。
ライセンスキー
この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Pesapal Pay Gateway は、Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例: ライセンスの有効期限日とドメイン）、そして以下のボタンが表示されます：ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key。その下には Product: opencart-payment-pesapal という行と、vibefox.net のアカウントを開く Manage licenses and domains in your account のリンクがあります。キーを変更できるのは、この拡張機能に対する Modify 権限を持つ管理者ユーザーだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。
キーが受け付けられない場合、ブロックにその理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ストアのアドレスを変更した後、またはアカウントでドメイン枠を解放した後には、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認できたステータスで動作を続けます。
1 つのキーは 1 つのドメインで動作します。OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメイン枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、Pesapal はチェックアウトで購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。同じブラウザで管理画面にログインしている管理者ユーザーには、ストア内で決済方法が表示され、(unlicensed — visible to admins only) と表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアからは管理画面へのログインが見えないため、有効なキーがない場合は、決済方法がすべてのユーザーに対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。すでに開始された決済は引き続き確認され、取り消しを含む既存の決済に関する Pesapal の通知も引き続き適用されます。
ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Pesapal が表示されない: ライセンスが有効であること、Enable/Disable が有効であること、現在のモードの consumer key と consumer secret が入力されていること（サンドボックスモードでは Sandbox consumer key と Sandbox consumer secret、本番モードでは Live consumer key と Live consumer secret）、注文の通貨が KES、UGX、TZS、ZMW、RWF、USD のいずれかであることを確認してください。設定の上部の警告に問題が示されています。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。
決済は完了したが、注文がステータスなしのまま: 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 が現在のモードの consumer key または consumer secret を拒否しました。キーがモードに合っているか確認してください。サンドボックスのキーはサンドボックスでのみ、本番のキーは本番モードでのみ機能します。ログには Pesapal のエラーが表示されます。
購入者に「Pesapal is temporarily unavailable」と表示される: Pesapal に接続できなかったか、通知 URL を登録できませんでした。ログを確認して、もう一度お試しください。
購入者に「This payment method is not available. Please reload the checkout page.」と表示される: チェックアウトのセッションが注文と一致しなくなったか、その間に決済方法が無効化されました。購入者はチェックアウトページを再読み込みします。
購入者に「We could not verify the Pesapal payment」と表示される: Pesapal からの戻りリンクが、ストアのどの注文とも一致しませんでした。料金が請求されている場合は、Pesapal ダッシュボードで決済を探し、購入者が再度支払う前に注文を確認してください。
モードを切り替えた後、以前のモードの決済が確認されない: 決済は、開始されたモードのキーで照合されます。そのモードの決済が確認されるまで、そのモードのキーを入力したままにしてください。
決済の後で注文が保留ステータスになっている: VibeFox Pesapal Pay Gateway タブのメモを確認してください。支払われた金額または通貨が注文と異なっていたか、注文のキャンセル後に決済が届いた可能性があります。Pesapal ダッシュボードで決済を確認してから、注文を処理するか、決済を返金してください。
開発者向け: 拡張機能は OpenCart のイベント pesapal_p_supported_currencies（通貨の一覧）と pesapal_p_submit_order_payload（Pesapal に送信する前の決済リクエスト）を発生させます。
アンインストール
Extensions > Extensions に移動し、種類 Payments を選択して、VibeFox Pesapal Pay Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は拡張機能自身の設定を常に削除します：Enable/Disable、Sort Order、Geo Zone、Total、および 注文ステータスのセクションにある注文ステータスです。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベント、キャッシュされた Pesapal のアクセストークン、登録済みの通知 ID も常に削除されます（OpenCart 4 では、そのイベントと起動アクションも削除されます。起動アクションにより、メンテナンスモードでも通知と購入者の戻りが通過します）。Delete data がオンの場合は、その他の設定（タイトル、説明、サンドボックスモード、キー、デバッグログのスイッチ）とログも削除されます。オフの場合は、後で再インストールするために保持されます。Pesapal の決済試行の記録は常に保持されます。既存の注文は、決済メモと Pesapal の追跡 ID を保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Pesapal Pay Gateway の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱ボタン）をクリックします。
Pesapal は、それぞれの所有者の商標です。この拡張機能は Pesapal と提携しておらず、Pesapal による承認も受けていません。