VibeFox OpenPay for WooCommerce — ヘルプ

要件

WordPress：6.0 以降。

WooCommerce：8.0 以降。インストールされ、有効になっている必要があります。WooCommerce がなければプラグインは有効化できません。

PHP：8.0 以降。

HTTPS：カードフォームはチェックアウトページにあるため、サイトは HTTPS を使用している必要があります。

OpenPay アカウント：メキシコ、コロンビア、またはペルーの OpenPay アカウント。その Merchant ID、秘密鍵（sk_...）、公開鍵（pk_...）が必要です。サンドボックスと本番のダッシュボードでは Merchant ID とキーが異なり、プラグインはそれらを区別して管理します。

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

カード情報はお使いのチェックアウトページに入力されますが、読み取りとトークン化はブラウザー内で openpay.js が行います。カードのフィールドには名前がなく、貴店のサーバーに送信されることはありません。カードフォームはお使いのページにあるため、PCI DSS の対象範囲は SAQ A-EP になります。詳細は加盟店契約先にご確認ください。

インストール

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

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

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

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

5. Account country を選び、サンドボックスと本番のキーを入力します（「構成」を参照）。

6. 推奨：OpenPay ダッシュボードに Webhook URL を追加します（「構成」を参照）。

7. Enable / Disable を有効にして保存します。OpenPay のサンドボックス用テストカードで決済をテストし、実際の決済を受け付けるには Sandbox mode のチェックを外します。

構成

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > OpenPay。フィールドの上には、現在のモードのキーが不完全な場合（その場合、チェックアウトで決済方法は非表示になります）、ストアの通貨が選択したアカウント国で受け付けられない場合に警告が表示され、サンドボックスモードが有効な間は Sandbox mode is enabled — no real charges are made. と表示されます。決済方法の一覧では、現在のモードに 3 つのキーがすべて揃うまで OpenPay は設定が必要と表示され、サンドボックスモードが有効な間はテストモードのバッジが表示されます。

保存時にキーが検証されます。Merchant ID には英字と数字のみを含めることができ、秘密鍵は sk_、公開鍵は pk_ で始まる必要があります。無効な値は保存されず、以前の値が保持されてエラーが表示されます。たとえば Sandbox: The private key must start with sk_. のように表示されます。決済方法が有効でも現在のモードのキーが不完全な場合は、ゲートウェイがチェックアウトで非表示のままであることを示すメッセージも表示されます。

一般

Enable / Disable：Enable OpenPay card payments で、この決済方法のオン／オフを切り替えます。初期値：オフ。

Title：チェックアウトで購入者に表示される決済方法の名称。初期値：Credit or debit card (OpenPay)。

Description：チェックアウトでカードフォームの上に表示されるテキスト。初期値：Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure)。

OpenPay アカウント

Merchant ID、秘密鍵（sk_）、公開鍵（pk_）は、OpenPay ダッシュボードの Settings (Configuración) にあります。このセクションには、メキシコ、コロンビア、ペルーのサンドボックスと本番のダッシュボードへのリンクがあります。

Account country：OpenPay アカウントの国です。OpenPay API、その国の openpay.js ライブラリ、受け付ける通貨を決定します。初期値：Mexico。

Sandbox mode：Use the OpenPay sandbox (test keys, no real charges) を選ぶと、キーと API の両方がサンドボックスに切り替わります。有効な間、チェックアウトには SANDBOX MODE のバッジが表示されます。初期値：オン。実際の決済を受け付けるには、チェックを外します。

Sandbox Merchant ID：サンドボックスのダッシュボードの Merchant ID（Settings (Configuración)、API キー）。

Sandbox Private Key：サンドボックスの秘密鍵。sk_ で始まります。サーバーでのみ使用され、決して共有しないでください。

Sandbox Public Key：サンドボックスの公開鍵。pk_ で始まります。openpay.js がブラウザー内でカードをトークン化するために使用します。

Live Merchant ID：本番のダッシュボードの Merchant ID（Settings (Configuración)、API キー）。

Live Private Key：本番の秘密鍵（sk_...）。

Live Public Key：本番の公開鍵（pk_...）。

プラグインのバージョン 1.0 のキー（キーのセットとサンドボックスフラグ）は、サンドボックスまたは本番のフィールドに自動的に移行されます。

Webhook

Webhook は必須ではありませんが、設定することをお勧めします。購入者が 3D Secure のページから戻らない場合（ブラウザーを閉じた場合など）に、決済を確認します。OpenPay ダッシュボードで Settings > Webhooks に進み、設定のこのセクションに表示される URL を追加します。形式は次のようなものです：https://your-site/wc-api/webhook_wc_openpay/。設定に表示されているとおりに正確にコピーしてください。使用する各モード（サンドボックスと本番）のダッシュボードに Webhook を追加します。

Webhook を追加すると、OpenPay はこの URL に確認コードを送信します。そのコードは受信日とともにこのセクションに表示されるので、OpenPay ダッシュボードで Webhook を確認できます。

次のイベントを選択します。

OpenPay は Webhook に署名しないため、プラグインは通知そのものを決して信頼しません。通知は課金を特定するためだけに使用し、その後、注文が支払われたモードの秘密鍵を使って OpenPay API から課金を読み取ります。このストアが作成していない課金に関する通知は無視されます。

詳細設定

Debug log：Log payment steps (errors are always logged) を有効にすると、決済の手順が WooCommerce > Status > Logs に、ソース wcp_openpay_gateway として書き込まれます。エラーと警告は、この設定がオフでも記録されます。キー、カードデータ、購入者の情報は決してログに記録されません。初期値：オフ。

Delete data on uninstall：Remove the gateway settings and logs when the plugin is deleted。初期値：オフ。

チェックアウト

購入者は決済方法（初期値は Credit or debit card (OpenPay)）を選択し、Cardholder name、Card number、Expiry (MM/YY)、Card code (CVV) を入力します。注文が送信されると、openpay.js がブラウザー内でカードを 1 回限りのトークンに変換し、OpenPay の不正検知ライブラリがデバイスセッション ID を追加します。貴店に送信されるのは、この 2 つの値だけです。

その後プラグインは、注文の合計金額について注文通貨で 3D Secure 付きの課金を作成し、OpenPay が提供する購入者の銀行の 3D Secure ページへ移動させます。各試行には OpenPay 内で独自の注文参照（注文番号と短いサフィックス）が割り当てられます。課金の説明は Order #、注文番号、サイト名です。購入者の名前、メールアドレス、電話番号は OpenPay に渡されますが、OpenPay に顧客アカウントは作成されません。購入者が 3D Secure のページにいる間、注文は 支払い待ち のままです。

購入者が戻ると、プラグインは OpenPay API から課金を読み取ります。注文は OpenPay が確認した後にのみ支払い済みとしてマークされます。課金はこの注文に属し、完了しており、注文の合計金額と通貨に正確に一致している必要があります。結果がまだ判明していない場合、注文受付ページに We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. と表示されます。その後、Webhook が注文を更新します。

カードが拒否されたり 3D Secure が失敗したりすると、購入者は Pay for order ページに戻り、The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. というメッセージが表示され、再度支払うことができます。新たな試行の前に、プラグインは注文の前回の課金を確認します。実際に支払い済みであれば、2 回目の課金は行わずに注文を支払い済みにします。まだ処理中であれば、購入者には前回の決済が処理中であることが表示され、再度支払わないよう案内されます。状態を確認できない場合は、新たな試行は行われず、数分後に再試行するよう購入者に求められます。

拒否されたカードには分かりやすいメッセージが表示されます。たとえば The card has insufficient funds. Please use another card.、The card has expired. Please use another card.、The security code (CVV) is not valid. Please check it and try again. などです。OpenPay の技術的なエラーが購入者に表示されることはありません。それらは注文メモとログに記録されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage（HPOS）と互換性があります。無効な場合、現在のモードのキーが不完全な場合、または注文の通貨がアカウント国で受け付けられない場合は、チェックアウトで非表示になります。

プラグインはカード決済のみに対応し、即時キャプチャされます。保存済みカード、サブスクリプション、無利子分割払い（MSI）や分割払い、カードポイント決済、現金、SPEI、PSE、CoDi 決済には対応していません。また、オーソリとキャプチャを分けて行うこともできません。

注文と返金

注文ステータス

支払い待ち：購入者が 3D Secure の画面にいるか、まだ支払いを完了していません。メモには課金 ID が表示されます。

処理中：支払いが確認されました。これは支払い後の WooCommerce の標準ステータスです。ダウンロード可能な仮想商品のみの注文は完了になります。注文メモには課金 ID とモード（本番またはサンドボックス）が表示されます。トランザクション ID は OpenPay の課金 ID です。

保留：課金が進行中でまだキャプチャされていない場合、または OpenPay が注文と異なる金額または通貨の完了した課金を報告した場合（注文は支払い済みになりません。メモに差異が表示されます）、または既にキャンセルされた注文に対して支払いが届いた場合です。OpenPay ダッシュボードで注文を確認し、そこで注文を完了させるか、決済を返金してください。

失敗：課金の作成時にカードが拒否されたか、直近の試行が失敗、キャンセル、または期限切れになりました。購入者は再度支払うことができます。

既に支払い済みの注文に対して 2 回目の完了した課金が届いた場合、注文は変更されません。WARNING で始まるメモが、OpenPay ダッシュボードで重複分を返金するよう求めます。

返金

メキシコとペルーのアカウントの場合：注文を開き、Refund をクリックして金額を入力し、Refund via Credit or debit card (OpenPay) をクリックします（ボタンには決済方法のタイトルが表示されます）。全額返金と一部返金に対応しています。返金は注文が支払われたモードとアカウント国で送信されるため、返金が必要なサンドボックスの注文が残っている間は、サンドボックスのキーを入力したままにしてください。OpenPay が返金を受け付けない場合、WooCommerce は OpenPay refund failed: ... などのエラーを表示し、返金は記録されません。成功した返金は、OpenPay の返金 ID とともに注文メモに追加されます。

公式の OpenPay プラグインと同様に、OpenPay Colombia は API を通じたカードの返金に対応していません。コロンビアの場合、返金ボタンは表示されません。OpenPay ダッシュボードで課金を返金してください。

OpenPay ダッシュボードで行われた返金やチャージバックは Webhook で届き、注文メモに一度だけ追加されます。WooCommerce の返金として自動的に記録されることはありません。必要に応じて、OpenPay ボタンを使わずに WooCommerce で手動の返金を作成してください。

ライセンスキー

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

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

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

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

トラブルシューティング

チェックアウトに OpenPay が表示されない：ライセンスが有効であること、Enable / Disable がオンであること、現在のモードに 3 つのキーがすべて揃っていること（サンドボックスモードではサンドボックスのキー、本番モードでは本番のキー）を確認してください。ストアの通貨が Account country で受け付けられているかも確認してください（メキシコ：MXN、USD。コロンビア：COP、USD。ペルー：PEN、USD）。設定ページには、いずれの場合も警告が表示されます。

支払いは完了したが、注文が支払い待ちのまま：購入者が 3D Secure のページから戻らず、Webhook が機能していません。使用しているモードの OpenPay ダッシュボードに Webhook URL が、設定に表示されたとおりに、上記のイベントとともに追加されているか確認してください。注文の支払いが行われたモードのキーが入力されているかも確認してください。キーがないと、Webhook は not configured と応答し、OpenPay は後で再試行します。

Webhook が ignored (unknown order) と応答する：この課金は、このストアがこの注文のために作成したものではありません。たとえば、同じ OpenPay アカウント上の別のショップの課金です。何も変更されません。

Webhook が verification failed と応答する：課金を読み取るための OpenPay API に接続できませんでした。OpenPay は Webhook を再試行します。

Webhook が busy と応答する：その瞬間、注文が別のリクエストによって更新されていました。OpenPay は Webhook を再試行します。

購入者に「The secure card form could not be loaded」と表示される：openpay.js または OpenPay の不正検知ライブラリがブラウザーで読み込めなかったか、デバイスセッション ID を作成できませんでした。購入者にページを再読み込みして再試行するよう依頼してください。

購入者に「The payment could not be processed right now」と表示される：OpenPay がリクエストを拒否したか、応答しませんでした。理由は注文メモとログ（ソース wcp_openpay_gateway）に記録されています。Merchant ID や秘密鍵の誤りが典型的な原因です。OpenPay から応答がなかった場合は、購入者が再度支払う前に、OpenPay ダッシュボードで課金を確認してください。

「This test card cannot be used for real payments」：サンドボックスモードがオフの状態で、サンドボックス用のテストカードが使用されました。

支払い後に注文が保留になる：注文メモを確認してください。課金がまだ進行中であるか、支払われた金額または通貨が注文と異なるか、注文がキャンセルされた後に支払いが届いたかのいずれかです。

モードに関するメッセージで返金が失敗する：注文はサンドボックスまたは本番モードで支払われましたが、そのモードのキーが設定されていません。キーを入力して、もう一度試してください。

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

アンインストール

プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページでプラグインを無効化してから削除します。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイの設定、保存された Webhook の検証コード、プラグインのログは、Delete data on uninstall がオンの場合にのみ削除されます。それ以外の場合は、後日再インストールするために残ります。注文データは常に保持されます。既存の注文は、支払いメモ、トランザクション ID、そして再インストール後の返金に必要な課金データを保持します。

OpenPay は各所有者の商標です。本プラグインは OpenPay と提携しておらず、OpenPay による承認も受けていません。