VibeFox Moyasar for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 8.0 以降。インストールされ、有効になっている必要があります。古いバージョンの WooCommerce では、プラグインは通知を表示し、読み込まれません。

PHP: 8.0 以降。

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

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

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

インストール

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

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

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

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

5. Moyasar のシークレットキーを貼り付けて保存します。設定に表示される URL と共有シークレットを使用して、Moyasar Dashboard でウェブフックを設定します（設定の項を参照）。

6. Enable/Disable をオンにします。テストモードでテスト注文を行ってから、Test mode のチェックを外します。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Moyasar。ページタイトルには TEST MODE または LIVE のバッジが表示されます。フィールドの上には、現在のモードにシークレットキーがない場合（その場合、チェックアウトで支払い方法は表示されません）や、ストアの通貨がサポートされていない場合に警告が表示されます。テストモードが有効な間は、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: Enable test mode はテスト用のシークレットキーを使用します。支払いはシミュレートされ、料金は請求されません。既定値：オン。実際の支払いを本番用シークレットキーで受け付けるには、オフにします。

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

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

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

ウェブフックは推奨されますが、必須ではありません。注文は、購入者がストアに戻ったときや、請求書が支払われたときに Moyasar がストアへ自動的に送信する請求書通知によっても確認されます。ウェブフックは、戻る前にブラウザを閉じた購入者にも対応し、Moyasar Dashboard で行われた返金も通知します。Moyasar Dashboard > Settings > Webhooks で、このセクションに表示される URL と共有シークレットを使ってウェブフックを追加します。HTTP メソッドは POST です。

Webhook URL: 読み取り専用で表示され、Copy ボタンがあります。形式は次のようになります：https://your-site/wp-json/moyasar_p/v1/webhook。HTTP メソッド：POST。

Webhook shared secret: Moyasar 上のウェブフックの Shared secret と同じ値を入力します。空欄のまま保存すると、ランダムなシークレットが生成されます。その後 Show をクリックし、Moyasar にコピーします。正しい共有シークレットがないウェブフックは拒否されます。

ウェブフックには、次のイベントを選択します：

payment_paid: 購入者が請求書を支払いました。

payment_failed: 支払いが失敗しました。

payment_refunded: 支払いが返金されました（例：Moyasar Dashboard での返金）。

payment_voided: 支払いが取り消されました。

ウェブフックや通知がそのまま信頼されることはありません。プラグインは、それぞれについて、注文のモードのシークレットキーを使用して Moyasar API から請求書を読み取り、その請求書がこの注文用に作成されたものかを確認します。同じ Moyasar アカウント上の他の連携による支払いは無視されます。

注文

Status after payment: 支払いが確認された後に設定される注文のステータスです。ステータスは直ちに設定され、ステータス変更は 1 回だけ行われます。

Processing: WooCommerce の標準設定です（既定値）。ダウンロード可能な仮想商品のみの注文は自動的に完了します。

Completed: 支払い済みのすべての注文が Completed になります。

On hold: 支払い済みのすべての注文は、手動で確認されるまで保留されます。

詳細設定

Debug log: Log API calls and notifications を有効にすると、詳細が WooCommerce > Status > Logs に、ソース wcp_moyasar_payment_gateway として書き込まれます。エラーは常に記録されます。API キー、カード情報、購入者の詳細は記録されません。既定値：オフ。

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted。注文に保存された支払い情報（Moyasar の請求書および支払い ID）は保持されるため、返金は引き続き追跡できます。既定値：オフ。

チェックアウト

購入者は支払い方法（既定では Pay with Moyasar）を選択して注文します。プラグインは、注文金額を注文通貨で Moyasar の請求書として作成し、購入者を決済ページに誘導します。購入者はそこで、貴店の Moyasar アカウントで有効になっている任意の方法（例：mada、Visa、Mastercard、Apple Pay、STC Pay）で支払います。請求書には Order、注文番号、貴店のサイト名が表示されます。

注文は、Moyasar が確認した後にのみ支払い済みとなります。プラグインは Moyasar API から請求書を読み取り、支払い済みであること、この注文に属していること、注文の金額と通貨が完全に一致していることを確認します。支払い後、購入者はストアの注文受付ページに戻ります。購入者が支払わずに戻った場合（例：決済ページの戻るボタンを使った場合）は、チェックアウトまたは Pay for 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 が支払いを開始できない場合、購入者には The Moyasar payment service is not responding. Please try again in a few minutes. などの短いメッセージが表示され、別の支払い方法を選ぶことができます。詳細はログに記録されます。

この支払い方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage（HPOS）に対応しています。

本プラグインは、Moyasar のページでの 1 回限りの支払いのみに対応しています。貴店のチェックアウトにカードフォームはなく、保存済みカードやトークン化、WooCommerce Subscriptions、個別のオーソリとキャプチャにも対応していません。

注文と返金

注文ステータス

Pending payment: 請求書は作成されましたが、購入者はまだ支払っていません。注文メモには、請求書 ID、金額、モードが表示されます。

Processing、Completed、On hold: 支払いが確認されました。ステータスは Status after payment の設定に従います。注文メモには、支払いの確認方法（ウェブフック、請求書通知、購入者の戻り、チェックアウト）、請求書 ID、支払い ID、支払い方法が表示されます。トランザクション ID は Moyasar の支払い ID です。

支払い後の On hold: Moyasar が注文合計と異なる金額または通貨を報告した（注文は支払い済みとしてマークされない）、または注文がキャンセルされた後に請求書が支払われた場合です。注文メモに理由が記載されています。Moyasar Dashboard で支払いを確認し、注文を処理するか、支払いを返金してください。

支払い前の On hold: Moyasar が支払いを審査のために保留しています。Moyasar が判断すると、注文が更新されます。

Failed: 未払い注文の最新の請求書が失敗、期限切れ、またはキャンセルされました。購入者は再度支払いを試みることができます。

Cancelled: 注文は、購入者、貴店、または WooCommerce の在庫保持タイムアウトによってキャンセルされました。注文の未処理の Moyasar 請求書もキャンセルされるため、もう支払うことはできません。

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

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Pay with Moyasar をクリックします（このボタンは支払い方法のタイトルを使用します）。Moyasar による支払いがある注文では、全額返金と一部返金に対応しています。2 時間以内に行われたカード支払いの全額返金は、取り消し（void、決済前のキャンセル）として送信されます。それ以外の場合は返金となります。返金には、支払いが行われたモード（テストまたは本番）のシークレットキーを使用するため、そのキーが設定されている必要があります。返金前に、プラグインは Moyasar で支払いの通貨、ステータス、返金可能な残額を確認します。Moyasar が返金を受け付けない場合、WooCommerce にエラーが表示され、返金は記録されません。返金または取り消しが成功すると、注文メモに追加されます。

Moyasar Dashboard で行われた返金と取り消しは、ウェブフックを通じて届きます。Moyasar が WooCommerce より多くの返金額を示している場合は、注文にメモが追加されます。これらは WooCommerce の返金として自動的に記録されることはありません。必要に応じて、Refund via Pay with Moyasar を使わずに、WooCommerce で手動返金を作成してください。

ライセンスキー

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

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

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

ライセンスの有効期限が切れてもプラグインは動作を続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。

トラブルシューティング

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

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

ウェブフックが Unauthorized を返す: Moyasar の共有シークレットが Webhook shared secret と一致していません。Show をクリックして値をコピーし、Moyasar のウェブフックに貼り付けてください。

ウェブフックが Webhook secret not configured を返す: 共有シークレットを指定して設定が保存されていません。設定を保存してシークレットを生成し、Moyasar にコピーしてください。

ウェブフックが Key not configured を返す: 注文は、シークレットキーが空のモード（テストまたは本番）で支払われました。そのキーを入力してください。

ウェブフックが Verification failed または Try again later を返す: Moyasar API から請求書を読み取れなかったか、同時に別のリクエストで注文が更新されていました。Moyasar はウェブフックを再試行します。

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

注文時に購入者にエラーが表示される: Debug log をオンにし、WooCommerce > Status > Logs をソース wcp_moyasar_payment_gateway で確認してください。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. は、その注文にはすでに支払い済みの請求書があり、貴店での確認が必要であることを意味します。

注文が On hold after payment になっている: 注文メモを確認してください。支払われた金額または通貨が注文と異なっていたか、注文がキャンセルされた後に支払いが届きました。注文を処理するか、支払いを返金してください。

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

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

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページでプラグインを無効化してから削除します。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定とログは、Clean uninstall がオンになっていた場合にのみ削除されます。そうでない場合は、後日の再インストールのために保持されます。既存の注文は、支払いメモとトランザクション ID を保持します。

Moyasar は、それぞれの所有者の商標です。本プラグインは Moyasar と提携しておらず、Moyasar による推奨もされていません。