VibeFox Moyasar for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは、それより古い PHP バージョンへのインストールを拒否します。

通貨: カートの通貨は SAR、AED、USD、EUR、KWD、BHD、OMR のいずれかである必要があります。それ以外の通貨の場合、チェックアウトでこの支払い方法は表示されません。

Moyasar アカウント: Moyasar アカウントのシークレット API キー（テストと本番）が必要です。使用するのはシークレットキーのみです。支払いは Moyasar のページで行われるため、公開可能キーは不要です。Moyasar Dashboard でのウェブフック設定を推奨します（「設定」を参照）。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後で、モジュール一覧から VibeFox Moyasar Payment Gateway を見つけて Configure をクリックすることもできます。

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

4. Moyasar のシークレットキーを貼り付け、Save をクリックします。Moyasar Dashboard でウェブフックを設定します（「設定」を参照）。

5. Enable/Disable をオンにして Save をクリックします。テストモードでテスト注文を行い、その後 Test mode をオフにします。

インストール時に、モジュールは 2 つの注文ステータスを作成します：Awaiting Moyasar payment と Moyasar payment on hold。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。これらは Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上部には、現在のモードにシークレットキーがない場合（この場合、チェックアウトで支払い方法は表示されません）、保存されたウェブフックの共有シークレットがない場合（この場合、ウェブフックはすべての呼び出しを拒否します）、またはストアの既定の通貨がサポートされていない場合に、警告が表示されます。モジュールがテストモードで有効になっている間は、Test mode is active: payments are simulated, no money is charged. と表示されます。保存時、モジュールは公開可能キー、他のモードのキー、またはスペースを含むキーを拒否し、以前の値を保持して理由を表示します。

Moyasar

Enable/Disable: Enable Moyasar で支払い方法をオンまたはオフにします。既定値：オフ。

Title: チェックアウトで顧客に表示される支払い方法の名前です。注文に保存される支払い方法名としても使われます。既定値：Pay with Moyasar。必須。

Description: チェックアウトで支払い方法の下に表示されるテキストです。既定値：You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. テストモードでは、チェックアウトに (Test mode: no real payment is made.) が追加されます。

API キー

シークレットキーは Moyasar Dashboard > Settings > API Keys からコピーします。テストキーと本番キーは別々です。テストモードではテストキーのみを、本番モードでは本番キーのみを使用します。

Test mode: テスト用のシークレットキーを使用します。支払いはシミュレートされ、料金は請求されません。既定値：オン。本番のシークレットキーで実際の支払いを受け付けるには、オフにします。

Test secret key: テストモードのシークレットキーです。sk_test_ で始まります。

Live secret key: 本番モードのシークレットキーです。sk_live_ で始まります。

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

支払い通知（ウェブフック）

ウェブフックは推奨されますが、必須ではありません。注文は、購入者がストアに戻ったときと、請求書が支払われたときに Moyasar が貴店へ自動的に送信する請求書通知によっても確認されます。ウェブフックは、戻る前にブラウザを閉じた購入者にも対応し、Moyasar Dashboard で行われた返金も通知します。Moyasar Dashboard > Settings > Webhooks で追加してください。

Webhook URL: 読み取り専用で表示され、Copy ボタンが付いています。フレンドリー URL を使用している場合、https://your-shop/module/wcp_moyasar_payment_gateway/webhook のような形になります。場合によっては /en/ のような言語コードが付くこともあります。設定に表示されたとおりに URL をコピーしてください。HTTP メソッド：POST。

Webhook shared secret: Moyasar 側のウェブフックの Shared secret と同じ値を入力します。何も保存されていない場合、Save はランダムなシークレットを生成します。Generate a new secret は保存済みのシークレットを置き換えます。生成されたシークレットは、保存後に設定の上部に一度だけ表示され、その後は表示されないため、すぐに Moyasar へコピーしてください。正しい共有シークレットがないウェブフックは拒否されます。

このウェブフックに対して、次のイベントを選択します（このセクションにも記載されています）：

ウェブフックや通知の内容は、そのまま信頼されることはありません。それぞれについて、モジュールは請求書が作成されたモードのシークレットキーを使って Moyasar API から請求書を読み取り、その請求書がこのカート用に作成されたことを確認します。同じ Moyasar アカウント上の他の連携による支払いは無視されます。1 つの共有シークレットが両方のモードで使われます。

注文

Status after payment: 支払いが確認された後に設定される注文ステータスです。注文はこのステータスで直接作成されます。

詳細設定

Clear saved secrets: Test secret key、Live secret key、または Webhook shared secret にチェックを入れて Save をクリックすると、削除されます。空のフィールドは、保存済みの値を保持します。

Debug log: API 呼び出しと通知を、モジュールのフォルダ内の logs/moyasar_p_debug.log.php に記録します。このファイルは Web から開くことはできません。エラーと警告は常に記録されます。API キー、カード情報、顧客情報は記録されません。既定値：オフ。

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

Clean uninstall: オンにすると、モジュールのアンインストール時にモジュールの設定とログが削除されます。注文と一緒に保存された支払い情報（Moyasar の請求書 ID と支払い ID）は保持されるため、返金は引き続き追跡できます。既定値：オフ。

チェックアウト

支払いの手順で、顧客は支払い方法（既定では Pay with Moyasar）を選び、確定します。モジュールは、カートの合計金額をカートの通貨で Moyasar の請求書として作成し、顧客をその支払いページに移動させます。顧客はそこで、Moyasar アカウントで有効になっている任意の方法で支払います。請求書には Order #、カート番号、貴店の名前が表示されます。この時点では、まだ注文は存在しません。

注文は、Moyasar が確認した後にのみ支払い済みとしてマークされます。モジュールは Moyasar API から請求書を読み取り、支払い済みであること、このカートに属すること、カートの金額と通貨が正確に一致することを確認します。その後、注文が作成され、顧客には標準の注文確認ページが表示され、Your payment with Moyasar has been received. と表示されます。Moyasar が支払いを審査のために保留した場合、ページには Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. と表示されます。注文が貴店の審査のために保留されている場合、ページには支払いを受け取り、注文を審査中であることが表示されます。審査中の支払いが後に失敗した場合、または未払いの注文がキャンセルされた場合、ページには Your Moyasar payment was not completed. Please contact us about this order. と表示されます。

顧客が支払わずに戻った場合（例：決済ページの戻るボタンを使用）、次のいずれかのメッセージとともにチェックアウトに戻ります：The payment at Moyasar was not completed. You can try again or choose another payment method.、Your Moyasar payment was declined or has expired. Please try again or choose another payment method.、または支払いをまだ確認できない場合は We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again.。カートは保持されます。

顧客は再度試すことができます。カートの開いている決済ページの金額と通貨が同じであれば、そのページが再利用されます。カートの合計金額が変更されていた場合は、古い決済ページが Moyasar でキャンセルされ、新しいページが作成されるため、古いページではもう支払えません。以前の請求書がすでに支払い済みであることが判明した場合は、新たな支払いではなく注文が作成されます。

Moyasar が支払いを開始できない場合、顧客はチェックアウトに留まり、The Moyasar payment service is not responding. Please try again in a few minutes. などの短いメッセージが表示され、別の支払い方法を選ぶことができます。詳細はログに記録されます。

ウェブフックと請求書通知は、ストアがメンテナンスモードの間も機能し、貴店の国別制限によってブロックされることはありません。

モジュールは、Moyasar のページでの 1 回限りの支払いのみに対応しています。貴店のチェックアウトにはカードフォームがなく、保存済みカードやトークン化、サブスクリプション、個別のオーソリとキャプチャもサポートしていません。

注文と返金

注文ステータス

注文はまだありません：顧客は Moyasar に移動しましたが、まだ支払っていないか、Moyasar がまだ支払いを確認していません。カートだけが存在します。

Payment accepted、Delivered、または Moyasar payment on hold：支払いが確認されました。ステータスは Status after payment に従います。支払いは Moyasar の支払い ID をトランザクション ID として記録されます。メモには、支払いがどのように確認されたか（ウェブフック、請求書通知、顧客の戻り、またはチェックアウト）、請求書 ID、支払い ID、支払い方法が表示されます。

Awaiting Moyasar payment：Moyasar が支払いを審査のために保留しています。Moyasar が支払いを確認すると、注文は支払い済みのステータスに移ります。

支払いエラー：審査中の支払いが失敗しました。

Moyasar payment on hold after payment：Moyasar がカートの合計金額と異なる金額または通貨を報告しました（例：支払いの開始後にカートが別のタブで変更された）。または、注文をキャンセルした後に請求書が支払われました。注文は支払い済みとはマークされませんが、実際に受け取った金額は注文の通貨である場合に記録されます。メモに理由が記載されています。Moyasar Dashboard で支払いを確認し、注文を処理するか、支払いを返金してください。

Refunded：モジュールを通じて、支払いが全額返金されました。

支払い済みの注文が、後から発生したイベントによって元に戻されることはありません。すでに支払い済みのカートについて 2 つ目の請求書も支払われた場合（例：2 つのブラウザタブから）、注文は変更されません。メモで、Moyasar Dashboard で重複した支払いを返金するよう案内されます。

Moyasar 支払いブロック

注文画面には Moyasar payment ブロックが表示され、Moyasar の請求書 ID、支払い ID、支払い方法（例：カードブランドと下 4 桁）、ステータス、支払い済み金額と返金済み金額、テスト支払い用の Test mode バッジ、返金履歴、および注文の Moyasar notes が表示されます。

返金

Moyasar payment ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via Moyasar をクリックします。Refund this amount through Moyasar? This cannot be undone. の確認に答えてください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。モジュールのページへのアクセス権は必要ありません。返金は Moyasar が請求した金額と通貨で行われるため、金額の不一致が生じた後は、注文の合計ではなく、顧客が実際に支払った金額までしか返金できません。2 時間以内に行われたカード支払いの全額返金は、取り消し（void）として送信されます。これは決済前の取り消しで、手数料はかかりません。それ以外の場合は返金となります。返金には、支払いが行われたモード（テストまたは本番）のシークレットキーが使用されるため、そのキーが設定されている必要があります。モジュールは、まず Moyasar で支払いの通貨、ステータス、返金可能額を確認します。Moyasar が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。成功した返金または取り消しは、返金履歴とメモに追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。返金は、Moyasar が支払いを確認した後に利用できます。

モジュールはクレジットスリップを作成しません。注文画面の標準の PrestaShop の返金ボタンでは、Moyasar を通じて返金されません。

Moyasar Dashboard で行われた返金と取り消しは、ウェブフックを通じて届きます。Moyasar が、モジュールが記録した以上の返金額を示している場合は、注文にメモが追加されます。注文ステータスとクレジットスリップは自動的に変更されません。必要に応じて、Refund via Moyasar を使わずに手動で更新してください。

ライセンスキー

モジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。License — VibeFox Moyasar Payment Gateway のライセンスブロックは、Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure ページで設定の上にある最初のブロックです。License key にキーを入力して Activate をクリックしてください。その後、ブロックにはキーがマスクされた状態、ステータス（ライセンスの有効期限日やお使いのドメインなど）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-payment-moyasar の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

チェックアウトに Moyasar が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードにシークレットキーがあること（テストモードでは Test secret key、本番モードでは Live secret key）、カートの通貨が SAR、AED、USD、EUR、KWD、BHD、OMR のいずれかであることを確認してください。キーがないか、ストアの通貨がサポートされていない場合、設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、顧客の国、顧客グループに対してモジュールが許可されているかを確認してください。

支払いは完了したが、注文が作成されなかった：確認がストアに届きませんでした。ウェブフックを設定してください。Moyasar Dashboard で、ウェブフックが存在すること、その URL が設定の Webhook URL と完全に一致すること、メソッドが POST であること、4 つのイベントがすべて選択されていること、そして共有シークレットが Webhook shared secret に保存されたものと同じであることを確認してください。注文は、顧客がストアに戻ったとき、または同じカートを再度支払おうとしたときにも作成されます。

ウェブフックが Unauthorized を返す：Moyasar の共有シークレットが保存されているものと異なります。Moyasar のウェブフックのシークレットを Webhook shared secret に入力して保存するか、Generate a new secret にチェックを入れて保存し、表示されたシークレットを Moyasar に貼り付けてください。

ウェブフックが Webhook secret not configured を返す：共有シークレットが保存されていません（例：Clear saved secrets で削除した後）。Save をクリックしてシークレットを生成し、Moyasar にコピーしてください。

ウェブフックが Key not configured を返す：請求書が、シークレットキーが空のモード（テストまたは本番）で作成されました。そのキーを入力してください。

ウェブフックが Verification failed または Try again later を返す：Moyasar API から請求書を読み取れなかった、同時に別のリクエストによってカートが更新されていた、または注文を作成できなかった（例：モジュールが無効になっている）のいずれかです。Moyasar はウェブフックを再試行します。理由を確認するには Debug log をオンにしてください。

ブラウザでウェブフック URL を開くと Method not allowed と表示される：これは正常です。この URL は Moyasar からの POST リクエストのみを受け付けます。

キーに関する保存時のエラー：公開可能キー（pk_...）または他のモードのキーが貼り付けられた、またはキーにスペースが含まれています。以前の値は保持されました。テストキーは sk_test_、本番キーは sk_live_ で始まります。

顧客が Moyasar を選択するとエラーが表示される：Debug log をオンにして、モジュールのページの Log フィールドを確認してください。This payment method is temporarily unavailable. Please choose another payment method or contact us. は通常、シークレットキーの誤りまたは未設定を意味します。A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. は、カートに支払い済みの請求書があるものの、注文に変換できなかったことを意味します。ログを確認してください。

Order is Moyasar payment on hold after payment：Moyasar payment ブロックの Moyasar notes を読んでください。支払われた金額または通貨がカートと異なっていた、または注文がキャンセルされた後に支払いが届いた、のいずれかです。注文を処理するか、支払いを返金してください。

返金に失敗する：メッセージを読んでください。支払いが別のモードで行われた場合は、そのモードのシークレットキーを入力してください。金額が Moyasar で返金可能な金額を超えている場合、支払いの一部はすでに返金されています（例：Moyasar Dashboard での返金）。Moyasar が返金済み金額を確認していない場合は、再試行する前に Moyasar Dashboard で支払いを確認してください。

アンインストール

Modules > Module Manager に移動し、VibeFox Moyasar Payment Gateway の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Clean uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合、後で再インストールできるようすべての設定が保持されます。Moyasar の請求書、支払い、返金、および注文ステータス Awaiting Moyasar payment と Moyasar payment on hold は常に保持されるため、再インストール後も古い注文を返金できます。既存の注文は、支払いのメモとトランザクション ID を保持します。

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