VibeFox Paymob for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールできません。

Paymob アカウント: 対応国のいずれかの加盟店アカウント: エジプト、アラブ首長国連邦、サウジアラビア、オマーン、パキスタン。Paymob の管理画面から 4 つの値が必要です: API key、オンライン決済連携の integration ID、決済ページの iFrame ID、HMAC secret。

通貨: カートの通貨は、お使いの Paymob の国の通貨である必要があります: エジプトは EGP、アラブ首長国連邦は AED、サウジアラビアは SAR、オマーンは OMR、パキスタンは PKR。別の通貨の場合、チェックアウトで支払い方法は表示されません。複数通貨の Paymob アカウントには対応していません。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox Paymob Pay を探し、Configure をクリックすることもできます。

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

4. Paymob country を選択し、API key、integration ID、iFrame ID、HMAC secret を入力します（設定を参照）。

5. Paymob の管理画面で、連携の callback URL を Configure ページに表示される URL に設定します（Callbacks を参照）。

6. Enable/Disable をオンにして Save をクリックします。Paymob のテスト連携の ID でテスト決済を行い、その後に本番連携の ID を入力します。

インストール時に、モジュールは 2 つの注文ステータスを作成します: Awaiting Paymob payment と Paymob payment on hold。PrestaShop は、新しい決済モジュールをすべての通貨、国、顧客グループに対して初期設定で有効にします。これらは Payment > Preferences で制限できます。後からショップで有効にした国も、このモジュールについてそこでチェックを入れる必要があります。

設定

すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox Paymob Pay > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。項目の上部では、Paymob の 4 つの値のいずれかが欠けている場合（それまでは Paymob がチェックアウトに表示されません）や、選択した Paymob の国がショップの初期通貨を受け付けない場合に、ページが警告を表示します。Callbacks ボックスには、Copy ボタン付きで callback URL が表示され、選択した国の Paymob 管理画面へのリンクがあります。

Paymob

Enable/Disable: Enable Paymob は、決済方法をオンまたはオフにします。初期値: オフ。

Title: チェックアウトで購入者に表示される決済方法の名称です。注文に保存される決済方法名にもなります。初期値: Paymob。

Description: チェックアウトで決済方法の下に表示されるテキストです。初期値: Pay securely by card or mobile wallet on the Paymob payment page. 空欄にすると、テキストは表示されません。

Paymob アカウント

すべての値は、Paymob の加盟店管理画面にあります。個別のテストモードはありません。テスト決済の場合は、テストモードの連携の integration ID を入力します。その他の設定は変更されません。

Paymob country: Paymob アカウントの国です。API と決済ページのサーバーを選択し、カートの通貨はこの国の通貨である必要があります。初期値: Egypt。

API key: Paymob の管理画面の Settings > Account info > API Key にあります。

Integration ID: Paymob の管理画面の Developers > Payment Integrations にある、カードまたはウォレットのオンライン連携の数値 ID です。Paymob のページで提供される決済方法は、この連携のものです。

iFrame ID: Paymob の管理画面の Developers > iframes にある、決済 iFrame の数値 ID です。

HMAC secret: Paymob の管理画面の Settings > Account info > HMAC にあります。必須: 注文は、この秘密鍵で署名されたコールバックからのみ支払い済みとして作成されます。

Integration ID と iFrame ID には数字のみを使用できます。スペースは削除されます。それ以外の値は保存時に拒否され、must contain digits only — the previous value was kept というメッセージが表示されます。その他の項目は保存されます。

保存された API key と HMAC secret は、再度表示されることはありません。項目は空のままになり、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ、新しい値を入力します。

Clear saved secrets: API key または HMAC secret にチェックを入れて Save をクリックすると、削除されます。項目が空欄の場合は、保存された値が維持されます。

Callbacks

Paymob は、各トランザクションをお使いのショップに通知します。Paymob の管理画面で Developers > Payment Integrations を開き、連携を選んで Edit をクリックし、Transaction processed callback と Transaction response callback の両方を、Callbacks ボックスに表示される URL に設定します。フレンドリー URL の場合は、https://your-shop/module/wcp_paymob_pay/callback のような形になり、/en/ のような言語コードが付くこともあります。URL はショップの初期言語で生成されます。Copy ボタンでコピーします。テスト連携を含め、使用するすべての連携で URL を設定してください。

Transaction processed callback は Paymob のサーバーから送信されます。Transaction response callback は、購入者をショップに戻します。どちらも HMAC secret で署名されており、モジュールが検証します。有効な署名がないコールバックは拒否され、何も変更されません。サーバーコールバックが遅れたり失われたりした場合は、署名付きの購入者の戻りによっても支払いが確認されます。サーバーコールバックは、ショップがメンテナンスモードの間も機能し、ショップの国別制限によってブロックされることはありません。

詳細設定

Debug log: 決済のステップとコールバックを、モジュールのフォルダ内の logs/paymob_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。エラーと拒否されたコールバックは、オフの場合でも常に記録されます。キー、トークン、購入者のデータは一切書き込まれません。初期値: オフ。

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

Clean uninstall: オンの場合、モジュールをアンインストールするとモジュールの設定とログが削除されます。注文（支払いの試行）用に保存された Paymob ID と注文ステータスは、常に保持されます。初期値: オフ。

チェックアウト

支払いのステップで、購入者は決済方法（初期値は Paymob）を選び、確定します。モジュールは、カートの通貨でカート合計に対する新しい Paymob 注文を登録し、購入者の氏名、メールアドレス、電話番号、請求先住所を Paymob に渡して、お使いの国の Paymob 決済ページに購入者を移動させます。そこで購入者は、カードやモバイルウォレットなど、お使いの連携のいずれかの方法で支払います。この時点では、まだ注文は存在しません。

支払い後、購入者はショップに戻ります。注文は、Paymob が署名付きトランザクションで確認した後にのみ支払い済みとしてマークされます。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。保留中の支払い（現金払いやキオスクなど）や承認済みの支払いでも、待機ステータスの注文が作成され、確認ページに移動します。

同じタイミングで Paymob のコールバックによって注文が確認されている場合、購入者には Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. というメッセージが表示されたページが表示されます。保留中の支払いの場合は、Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. というテキストになります。ページには Check again ボタンと Back to checkout ボタンがあります。

支払いが拒否された場合、購入者は同じカートでチェックアウトに戻り、Your Paymob payment was not completed. Please try again or choose another payment method. というメッセージが表示されます。新しい試行のたびに、それぞれ個別の Paymob 注文が登録されるため、購入者はカートの支払いを再度行うことができます。Paymob からの応答を確認できない場合、購入者には We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment. が表示されます。

Paymob が支払いを開始できない場合、購入者はチェックアウトに留まり、Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. や Could not connect to Paymob. Please try again in a moment. などの短いメッセージが表示されます。技術的な理由はログに書き込まれます。

このモジュールは、Paymob のページで 1 回限りの支払いを処理します。保存されたカード、サブスクリプション、サイト上に埋め込まれたカードフォーム、管理画面からの返金には対応していません。

注文

注文ステータス

No order yet: 購入者は Paymob に移動しましたが、まだ支払っていないか、支払いが拒否されたか、Paymob がまだ支払いを確認していません。カートだけが存在します。

Payment accepted: Paymob が支払いを確認しました。支払いは、Paymob のトランザクション ID をトランザクション ID として記録され、備考にはトランザクション、金額、カードの種類と下 4 桁が表示されます。

Awaiting Paymob payment: 支払いは Paymob で保留中です（現金払いやキオスクでの支払いなど）。Paymob が支払いを確認すると、注文は Payment accepted に移動します。

Paymob payment on hold: Paymob は金額を承認しただけで、売上確定（キャプチャ）していません（Paymob の管理画面で売上確定してください。キャプチャのコールバックが届くと、注文は Payment accepted に移動します）。または、支払われた金額や通貨がカートと異なります（例: 支払いの開始後にカートが変更された）。または、キャンセル済みの注文に対する支払いが届きました。備考に理由が記載されます。注文を確認して処理するか、Paymob の管理画面で支払いを返金してください。

すでに支払い済みの注文に対して 2 回目の成功した支払いが届いた場合、注文は変更されません。備考で、重複分を Paymob の管理画面で返金するよう求められます。以前に支払い済みだったキャンセル済みの注文や、返金済みの注文に対する支払いは、備考を追加するだけで、注文は再開されません。まだ支払い済みでない注文に対する拒否された支払いは、備考を追加するだけです。

Paymob 支払いブロック

注文ページには、注文ごとの Paymob の各試行を示す Paymob payment ブロックが表示されます: Paymob の注文、加盟店の注文 ID と国、Paymob のトランザクション ID、ステータス、リクエストされた金額、カードについて Paymob が報告した金額、そして Paymob のメッセージです。その下には、この注文に対するモジュールの Notes があります。

返金

管理画面からの返金には対応していません。Paymob の管理画面で支払いを返金またはキャンセルしてください。Paymob が返金またはキャンセルを報告すると、注文に備考が追加されますが、注文ステータスは変更されません。注文ステータスやクレジットスリップなど、注文を手動で更新してください。

ライセンスキー

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

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

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

有効なキーがない場合、チェックアウトで購入者に Paymob は表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、支払い方法はあなたにも非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された支払いは、引き続き確認されます。

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

トラブルシューティング

チェックアウトに Paymob が表示されない: ライセンスが有効か、Enable/Disable がオンか、4 つの値（API key、integration ID、iFrame ID、HMAC secret）がすべて入力されているか、そしてカートの通貨が選択した Paymob country の通貨か確認してください。何かが欠けている場合、設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているか確認してください。

支払いは完了したが、注文が作成されなかった: コールバックがショップに届いていません。お使いの連携の Transaction processed callback と Transaction response callback が、Callbacks ボックスに表示される URL と完全に一致しているか、そして HMAC secret が同じ Paymob アカウントのものか確認してください。拒否されたコールバックは、Debug log がオフの場合でも警告としてログに書き込まれます。モジュールのページの Log 欄を確認してください。

コールバックが Invalid signature を返す: 設定の HMAC secret が Paymob アカウントと一致しないか、別の国のアカウントが選択されています。HMAC secret を再度コピーしてください。

コールバックが Not configured を返す: HMAC secret が空です。シークレットを入力してください。Paymob はコールバックを再試行します。

コールバックが locked または retry を返す: 購入者の戻りなど、別のリクエストが同時に注文を更新していた、または注文を作成できませんでした（例: モジュールが無効になっている）。Paymob はコールバックを再試行します。理由はログに書き込まれます。

ブラウザでコールバック URL を開くと、could not verify のメッセージが表示されたチェックアウトに移動する: これは正常です。この URL は、Paymob からの署名付きリクエストのみを受け付けます。

購入者が Paymob を選ぶ際にエラーが表示される: Debug log をオンにして、ログを確認してください。Paymob payments are temporarily unavailable は、API key が誤っているか、値が欠けていることを意味します。Paymob could not start the payment は、integration ID の誤りや請求情報の不備などにより、Paymob がリクエストを拒否したことを意味します。This order cannot be paid with Paymob は、注文の合計金額がゼロであることを意味します。Paymob does not accept payments in の後に通貨が続く場合は、カートの通貨が選択した Paymob の国の通貨ではないことを意味します。

支払い後に注文が Paymob payment on hold または Awaiting Paymob payment になっている: Paymob payment ブロックの備考を確認してください。支払いは保留中（現金またはキオスク）であるか、トランザクションは承認のみで（Paymob の管理画面で売上確定してください）、金額または通貨が一致しなかったか、注文のキャンセル後に支払いが届いています。

テスト決済: Integration ID に Paymob のテスト連携の ID を入力し、その連携でコールバック URL を設定してください。本番の決済の場合は、本番連携の ID を再度入力してください。

アンインストール

Modules > Module Manager に進み、VibeFox Paymob Pay の横のメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Clean uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合は、後で再インストールできるようにすべての設定が保持されます。注文の Paymob 支払い試行と、注文ステータス Awaiting Paymob payment および Paymob payment on hold は、常に保持されます。既存の注文は、支払いの備考、トランザクション ID、Paymob ID を保持します。

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