VibeFox Paymob for OpenCart — ヘルプ

要件

OpenCart：3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。

PHP：8.0 以降。

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

通貨：チェックアウトの通貨は、Paymob の国の通貨である必要があります：エジプトは EGP、UAE は AED、サウジアラビアは SAR、オマーンは OMR、パキスタンは PKR です。ストアにまだない場合は System > Localisation > Currencies で追加してください。別の通貨の場合、チェックアウトで支払い方法は非表示になります。複数通貨の Paymob アカウントには対応していません。

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

インストール

ファイルは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。お使いのコンピューターで解凍してください。README.txt、OpenCart 3 用パッケージ wcp_paymob_pay-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_paymob_pay.ocmod.zip が含まれています。お使いの OpenCart バージョンのパッケージのみをインストールしてください。ライセンスキーは両バージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル wcp_paymob_pay-oc3-(version).ocmod.zip を選択します。本拡張機能には OCMOD の変更がないため、Extensions > Modifications を更新する必要はありません。インストーラーの代わりに、このパッケージの upload フォルダーの内容をストアのルートフォルダーにコピーすることもできます。

2. Extensions > Extensions に進み、タイプで Payments を選択します。VibeFox Paymob Pay を見つけて、Install（緑色の + ボタン）をクリックします。

3. Edit（鉛筆ボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（License key を参照）。

4. Paymob country を選択し、API キー、統合 ID、iFrame ID、HMAC シークレットを入力します（設定を参照）。

5. Paymob の管理画面で、連携のコールバック URL を Callbacks セクションに表示されている URL に設定します（Callbacks を参照）。

6. Enable/Disable をオンにして Save をクリックします。Paymob のテスト連携の ID でテスト支払いを行い、その後、ライブ連携の ID を入力します。

OpenCart 4

1. 管理画面で Extensions > Installer に進み、Upload をクリックして、ファイル wcp_paymob_pay.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。

2. パッケージは同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に進み、タイプで Payments を選択します。VibeFox Paymob Pay を見つけて、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆ボタン）をクリックします。

4. ライセンスキー、Paymob のキーと ID、コールバック URL は、OpenCart 3 の手順 3 から 6 と同じように入力します。設定ページとそのフィールドは両バージョンで同じです。コールバック URL のみ異なります（Callbacks を参照）。

新規インストール時は、支払い方法がオフの状態で始まります。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit。セクションは左側に並んでおり、一覧の下にある Save ボタンでページ全体を保存します。設定の上では、Paymob の 4 つの値のいずれかが欠けている場合（それまでは Paymob はチェックアウトで非表示になります）、およびストアのデフォルト通貨が選択した Paymob の国で受け付けられていない場合に、ページが警告します。

保存時、Title は 128 文字を超えてはならず、Sort Order は整数である必要があります（負の数も可）。Total は 0 以上の数値である必要があり、選択したジオゾーンと注文ステータスが存在している必要があります。そうでない場合は何も保存されず、ページにその項目が示されます。

Paymob

Enable/Disable：Enable Paymob は支払い方法をオンまたはオフにします。デフォルト：オフ。

Title：チェックアウトで購入者に表示される支払い方法の名前です。注文にも支払い方法名としてこの名前が保存され、128 文字まで使用できます。空の場合、購入者には Paymob と表示されます。デフォルト：Paymob。

Description：Confirm Order ステップで、確認ボタンの上に購入者に表示されるテキストです。デフォルト：Pay securely by card or mobile wallet on the Paymob payment page. 空欄にすると、テキストは表示されません。

Sort Order：チェックアウトの支払い方法の中での Paymob の位置です。空欄のままにするか、整数を入力します。

Geo Zone：選択したジオゾーン内の支払い住所に対してのみ Paymob を提供します。デフォルト：All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。OpenCart 4 では、ストアが支払い住所を求めない場合は配送先住所が使用されます。

Total：Paymob を提供するために注文が達している必要のあるチェックアウト合計金額（ストアのデフォルト通貨）です。空欄のままにすると、どの金額でも Paymob を提供します。

Paymob アカウント

すべての値は Paymob の加盟店管理画面にあります。独立したテストモードはありません。テスト支払いの場合は、テストモードの連携の統合 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 キーと HMAC シークレットは、二度と表示されません。欄は空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。保存済みの値を削除するには、欄の下にある Clear the saved API key on save または Clear the saved HMAC secret on save にチェックを入れて、Save をクリックします。

Callbacks

Paymob は、各取引を貴店に報告します。Paymob の管理画面で Developers > Payment Integrations を開き、連携を選択して Edit をクリックし、Transaction processed callback と Transaction response callback の両方を、このセクションに表示されている Callback URL に設定します。URL は次のような形式です。OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_paymob_pay/callback、OpenCart 4 では https://your-store/index.php?route=extension/wcp_paymob_pay/payment/wcp_paymob_pay.callback。OpenCart のインストール先のストアアドレスから作成されます。Copy ボタンでコピーできます。このセクションには、選択した国の Paymob 管理画面へのリンクもあります。テスト連携を含め、使用するすべての連携で URL を設定してください。

Transaction processed callback は Paymob のサーバーから送信されます。Transaction response callback は、購入者を貴店に戻します。どちらも HMAC シークレットで署名され、拡張機能によって確認されます。有効な署名のないコールバックは拒否され、何も変更しません。サーバーコールバックが遅れたり失われたりした場合は、署名された購入者の返却によっても支払いが確認されます。コールバック URL は、ストアがメンテナンスモードでも機能します。OpenCart 3 では支払い拡張機能のリクエストを通過させ、OpenCart 4 では拡張機能がコールバックと購入者の返却を通過させるスタートアップアクション（startup）を追加します。

注文

OpenCart は Confirm Order ステップで、ステータスなしで注文を作成します（欠落注文）。注文は、Paymob が正しく署名された取引を報告した後にのみステータスを受け取ります。拒否された支払いは注文をステータスなしのままにし、購入者はカートが保持された状態でチェックアウトに戻ります。以下の各フィールドには、OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment：Paymob の取引が、期待される金額と通貨で支払われました。デフォルト：処理中。

Awaiting Paymob Payment Status：取引が保留中です（例：現金やキオスクでの支払い）。Paymob が確認すると、注文は支払い後のステータスを受け取ります。デフォルト：保留中。

Paymob Payment On Hold Status：Paymob は金額を承認しただけです（Paymob の管理画面で売上確定してください）。支払われた金額または通貨が注文と異なるか、キャンセルされた注文に対して支払いが届きました。メモに理由が説明されます。デフォルト：保留中。OpenCart には On hold のステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

次の 3 つのフィールドは、ストアが使用しているステータスを拡張機能に伝えます。拡張機能はこれらを設定しません。

Payment Error Status：支払いエラーのある注文にストアが使用するステータスです。保留中の取引は、そのような注文を待機ステータスに移すことがあります。デフォルト：失敗。

Cancelled Order Status：キャンセルされた注文にストアが使用するステータスです。そのような注文に対して届いた支払いは、注文を保留にするか、以前に支払い済みだった場合はメモを追加するだけです。デフォルト：キャンセル。

Refunded Order Status：返金された注文にストアが使用するステータスです。そのような注文に対して届いた支払いは、メモを追加するだけです。デフォルト：返金済み。

詳細設定

Debug log：支払いの各ステップとコールバックを、OpenCart のログフォルダー（storage/logs）内の paymob_p_debug.log.php に記録します。このファイルは Web から開くことはできません。エラーと拒否されたコールバックは、オフでも常に記録されます。キー、トークン、購入者データは書き込まれません。デフォルト：オフ。

Log：ログのサイズと最新のエントリーを表示します。Clear log をクリックすると空になります。

Clean uninstall：オンの場合、拡張機能をアンインストールするとゲートウェイ設定とログが削除されます。注文に保存された Paymob ID（支払い試行）は常に保持されます。デフォルト：オフ。

インポート / エクスポート

Export：Download JSON は、設定を JSON ファイルとして保存します。API キーと HMAC シークレットはエクスポートされません。

Import：以前にエクスポートした JSON を貼り付けて、Import をクリックすると設定が復元されます。保存済みのシークレットは保持されます。

チェックアウト

Payment Method ステップで、購入者は支払い方法を選択します（デフォルトは Paymob）。Confirm Order ステップでは、購入者に貴店の説明文と、You will be redirected to the secure Paymob payment page to pay by card or mobile wallet. というメモが表示されます。OpenCart は、このステップでまだステータスのない注文を作成します。OpenCart 4 では、購入者は支払い方法欄の Choose ボタンで Payment method options ウィンドウから支払い方法を選び、チェックアウトページ下部の Confirm Order をクリックします。購入者が Confirm Order をクリックすると、拡張機能は注文通貨での注文合計に対する新しい Paymob 注文を登録し、購入者の名前、メールアドレス、電話番号、支払い住所（OpenCart 4 では、ストアが支払い住所を求めない場合は配送先住所）を Paymob に渡し、購入者を貴国の Paymob 決済ページに移動させます。そこで購入者は、連携で利用可能な方法（カードやモバイルウォレットなど）のいずれかで支払います。

支払い後、購入者は貴店に戻ります。注文が支払い済みとしてマークされるのは、Paymob が署名された取引で確認した後だけです。その後、注文は通常の注文メールと在庫更新とともに OpenCart の通常の方法でステータスを受け取り、購入者は OpenCart の注文完了ページを見ます。保留中の支払い（現金やキオスクなど）または承認された支払いも、注文に待機または保留のステータスを与え、完了ページに進みます。

購入者が戻った時点で注文がまだ確認中の場合、Payment confirmation ページに 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 注文が登録されるため、購入者はカートを再度支払うことができます。OpenCart 3 では Confirm Order ステップが表示されるたびに新しい注文が作成されます。OpenCart 4 では、チェックアウト用に 1 つの注文を保持して更新するため、購入者は同じ注文に対して新しい試行で支払います。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. と表示されます。同じカートの別の注文がすでに支払い済みか支払い待ちの場合（例：別のブラウザータブから）、購入者は再度支払う代わりに完了ページに移動します。OpenCart 4 では、Paymob からの戻り後のメッセージはチェックアウトページの上に表示されます。

OpenCart 4 は、成功ページが表示されるまで注文をチェックアウト中に保持します。その注文が支払いなしで閉じられていた場合（例：キャンセルした場合）、購入者は Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. のメッセージとともにチェックアウトに戻され、次の Confirm Order で新しい注文が支払われます。その注文にすでにステータスがあり、カートに別の商品や数量がある場合も、購入者はチェックアウトに戻され、新しいカートには新しい注文が作られます。

Paymob が支払いを開始できない場合、購入者は Confirm Order ステップにとどまり、ボタンの上に短いメッセージが表示されます。例：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 のページでの一回限りの支払いのみを受け付けます。保存されたカード、定期購読、自店サイトに埋め込まれたカードフォーム、管理画面からの返金には対応していません。

注文

注文ステータス

No status (missing order)：購入者は Paymob に送られたものの支払っていない、支払いが拒否された、または Paymob がまだ支払いを確認していません。Sales > Orders では、Order Status フィルターを Missing Orders に設定した場合にのみ、このような注文が表示されます。

OpenCart 4 では、支払いのないチェックアウトの注文が Voided ステータスになることがあります。これは、OpenCart 4 が購入者を Confirm Order ステップに戻したときに設定するものです。拡張機能はそのような注文をステータスなしの注文として扱い、後の支払いで引き続き確認されます。

Order Status After Payment (default Processing)：Paymob が支払いを確認しました。メモには、取引、金額、カードの種類と下 4 桁が表示されます。

Awaiting Paymob Payment Status (default Pending)：支払いが Paymob で保留中です（例：現金やキオスクでの支払い）。Paymob が支払いを確認すると、注文は支払い後のステータスに移ります。

Paymob Payment On Hold Status (default Pending)：Paymob は金額を承認しただけで、売上確定していません（Paymob の管理画面で売上確定してください。売上確定のコールバックが届くと、注文は支払い後のステータスに移ります）。または、支払われた金額または通貨が注文と異なります。または、キャンセルされた注文に対して支払いが届きました。メモに理由が説明されます。注文を確認し、対応するか、Paymob の管理画面で支払いを返金してください。

すでにステータスのある注文が変更されると、OpenCart は購入者に通知します。すでに支払い済みの注文に対して 2 回目の成功した支払いが届いた場合、または支払い済みのカートの 2 番目の注文に対する支払いが届いた場合、支払い済みの注文は変更されず、メモが重複分を Paymob の管理画面で返金するよう求めます。以前に支払い済みだったキャンセル済みの注文、または返金済みの注文に対する支払いは、メモを追加するだけです。注文は再開されません。すでにステータスのある注文に対する拒否された支払いは、メモを追加するだけです。

メモは、購入者には表示されない注文の History のエントリーです。

VibeFox Paymob Pay タブ

Sales > Orders で、Paymob で支払われた注文を開きます。注文ページの下部、History と Additional の横に、VibeFox Paymob Pay タブが表示され、注文の Paymob 試行ごとの情報が表示されます。加盟店の注文 ID と国を含む Paymob order、Paymob transaction ID、Status、Requested 金額、カード情報を含む Amount reported by Paymob、そして Paymob message です。その下には、この注文に対する拡張機能の Notes が表示されます。このタブは、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

管理画面からの返金には対応していません。Paymob の管理画面で支払いを返金またはキャンセルしてください。Paymob が返金またはキャンセルを報告すると、注文にメモが追加されますが、注文ステータスは変わりません。注文は手動で更新してください。

ライセンスキー

本拡張機能は、vibefox.net で入手した VibeFox ライセンスキーで動作します。License — VibeFox Paymob Pay ライセンスブロックは、Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例：ライセンスの有効期限日とお使いのドメイン）、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: opencart-payment-paymob の行と、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 のアカウントで枠を解放してください。

有効なライセンスキーがない場合、チェックアウトで Paymob は購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。同じブラウザーで管理画面にログインしている管理者ユーザーには、ストアで支払い方法が (unlicensed — visible to admins only) と表示された状態で引き続き見えるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理画面へのログインを確認できないため、有効なキーがないと支払い方法はすべてのユーザーに対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文は影響を受けません。すでに開始された支払いは引き続き確認されます。

ライセンスが期限切れになった場合も拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに Paymob が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、4 つの値（API キー、統合 ID、iFrame ID、HMAC シークレット）がすべて入力されていること、チェックアウトの通貨が選択した Paymob country の通貨であることを確認してください。設定ページは、何かが不足している場合に警告を表示します。また、支払い住所が選択した Geo Zone に含まれていること、そして注文が設定の Total に達していることも確認してください。

支払いは完了したが、注文がステータスのないまま：コールバックが貴店に届いていません。使用している連携の Transaction processed callback と Transaction response callback が、Callbacks セクションに表示されている URL と完全に一致していること、そして HMAC secret が同じ Paymob アカウントのものであることを確認してください。拒否されたコールバックは、Debug log がオフでも警告としてログに書き込まれます。拡張機能ページの Log フィールドを確認してください。

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

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

コールバックが locked または retry と応答する：購入者の返却など、別のリクエストが同じ瞬間に注文を更新していたか、注文ステータスを設定できませんでした。Paymob はコールバックを再試行します。理由はログに書き込まれます。

コールバック URL をブラウザーで開くと、確認できなかったというメッセージとともにチェックアウトに移動する：これは正常です。この URL は Paymob からの署名付きリクエストのみを受け付けます。

Confirm Order の後に購入者がエラーを見る：Debug log をオンにして、ログを確認してください。Paymob payments are temporarily unavailable は、API キーが誤っているか、値が不足していることを意味します。Paymob could not start the payment は、統合 ID が誤っている、または請求情報が不完全であるなどの理由で、Paymob がリクエストを拒否したことを意味します。This order cannot be paid with Paymob は、注文合計がゼロであることを意味します。Paymob does not accept payments in に続けて通貨が表示される場合は、注文の通貨が選択した Paymob の国の通貨ではないことを意味します。This payment method is not available. は、チェックアウトのセッションが注文と一致しなくなったか、その間に支払い方法がオフにされたことを意味します。購入者はチェックアウトを再読み込みしてください。

支払い後、注文が保留または待機ステータスになっている：VibeFox Paymob Pay タブのメモを確認してください。支払いが保留中（現金またはキオスク）である、取引が承認のみで売上確定されていない（Paymob の管理画面で売上確定してください）、金額または通貨が一致しなかった、または注文がキャンセルされた後に支払いが届いた、などが考えられます。

テスト支払い：Paymob のテスト連携の ID を Integration ID に入力し、その連携でコールバック URL を設定してください。実際の支払いの場合は、ライブ連携の ID を再度入力してください。

アンインストール

Extensions > Extensions に進み、タイプで Payments を選択して、VibeFox Paymob Pay の横にある Uninstall（赤色の − ボタン）をクリックします。ライセンスキーとライセンスステータスは、この拡張機能の分として常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します。Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスです。これらは再インストール時にデフォルトに戻ります。OpenCart 4 では、拡張機能の OpenCart イベントと、メンテナンスモードでコールバックと購入者の返却を通過させるスタートアップアクションも削除されます。Clean uninstall がオンの場合、他のゲートウェイ設定（タイトル、説明、国、キーと ID、ログ記録）とログも削除されます。オフの場合は、後で再インストールするために保持されます。注文の Paymob 支払い試行は常に保持されます。既存の注文は、支払いのメモと Paymob ID を保持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に進み、インストール済み拡張機能の一覧で VibeFox Paymob Pay の横の Uninstall（オレンジ色の − ボタン）をクリックし、次にアップロードしたパッケージを削除するために Delete（赤いごみ箱ボタン）をクリックします。

Paymob は、それぞれの所有者の商標です。本拡張機能は Paymob と提携しておらず、Paymob による推奨も受けていません。