VibeFox OpenPay for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

PHP：8.0 以降。モジュールは古い PHP バージョンへのインストールを拒否します。

HTTPS：カードフォームはチェックアウトページに表示されるため、貴店は HTTPS を使用する必要があります。

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

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

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

インストール

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

2. アップロードが完了したら Configure をクリックします。あるいは、後からモジュール一覧で VibeFox OpenPay Gateway を探し、Configure をクリックします。

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

4. Account country を選択し、サンドボックスと本番のキーを入力します（設定を参照）。

5. 推奨：OpenPay ダッシュボードに Webhook URL を追加します（設定を参照）。

6. Enable / Disable をオンにして Save をクリックします。OpenPay のサンドボックス用テストカードで決済をテストし、その後で本番の決済を受け付けるために Sandbox mode をオフにします。

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox OpenPay Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、現在のモードのキーが不完全な場合（決済方法はチェックアウトで非表示になります）、ストアの既定通貨が選択したアカウント国で受け付けられない場合に警告が表示され、サンドボックスモードがオンの間は Sandbox mode is enabled — no real charges are made. と表示されます。

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

OpenPay

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：OpenPay のサンドボックス（テストキー、実際の決済は発生しません）を使用し、キーと API の両方をサンドボックスに切り替えます。オンの間、チェックアウトに SANDBOX MODE バッジが表示されます。既定値：オン。実際の決済を受け付けるにはオフにします。

Sandbox Merchant ID：サンドボックスダッシュボードの Settings (Configuración)、API キーにある Merchant ID です。

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

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

Live Merchant ID：本番ダッシュボードの Settings (Configuración)、API キーにある Merchant ID です。

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

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

保存済みの秘密鍵は二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved secrets：秘密鍵にチェックを入れて Save をクリックすると削除されます。フィールドが空の場合は、保存済みの値が維持されます。

Webhook

Webhook は必須ではありませんが、設定をお勧めします。お客様が 3D Secure ページから戻らない場合（たとえばブラウザーを閉じた場合）に、決済を確認します。OpenPay ダッシュボードで Settings > Webhooks に進み、このセクションの Webhook URL に表示されている URL を追加します。フレンドリー URL を使用している場合、URL は https://your-shop/module/wcp_openpay_gateway/webhook のような形式になり、/en/ のような言語コードが付くこともあります。設定に表示されているとおりに正確にコピーしてください。使用する各モード（サンドボックスと本番）のダッシュボードに Webhook を追加してください。

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

次のイベントを選択します（これらもこのセクションに記載されています）：

OpenPay は Webhook に署名しないため、モジュールは通知そのものを決して信頼しません。通知は決済を見つけるためだけに使用され、その後、決済が行われたモードとアカウント国の秘密鍵を使って OpenPay API から決済情報を読み取ります。このストアが作成していない決済の通知は無視されます。Webhook はストアがメンテナンスモードでも動作し、ストアの国による制限でブロックされることはありません。

詳細設定

Debug log：決済の各ステップを、モジュールフォルダー内の logs/wc_opy_debug.log.php に記録します。このファイルはウェブから開くことはできません。オフの場合でも、エラーと警告は記録されます。キー、カードデータ、お客様の詳細は決して記録されません。既定値：オフ。

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

Delete data on uninstall：オンの場合、モジュールをアンインストールするとゲートウェイの設定、保存された Webhook 検証コード、ログが削除されます。注文の OpenPay 決済記録は支払い履歴のため常に保持されるので、再インストール後も注文を返金できます。既定値：オフ。

チェックアウト

支払いステップでお客様は決済方法（既定では Credit or debit card (OpenPay)）を選択し、Cardholder name、Card number、Expiry (MM/YY)、Card code (CVV) を入力します。サンドボックスモードでは、フォームに SANDBOX MODE — Test environment. No real charges will be made. が表示されます。お客様が確定すると、openpay.js がブラウザー内でカードを 1 回限りのトークンに変換し、不正検知ライブラリがデバイスセッション ID を追加します。貴店に送信されるのは、この 2 つの値とカート番号のみです。フォームが未入力のままの場合は、フォームの下に Please fill in all card fields. と表示されます。

その後、モジュールはカートの通貨で、カート合計に対する 3D Secure 付きの決済を作成し、お客様を OpenPay が提供する銀行の 3D Secure ページに移動させます。各試行には独自の OpenPay 注文参照番号が割り当てられます。決済の説明は Cart #、カート番号、貴店の名前です。お客様の名前、メールアドレス、電話番号は OpenPay に渡されますが、OpenPay 上に顧客アカウントは作成されません。この時点ではまだ注文は存在しません。

お客様が戻ると、モジュールは OpenPay API から決済情報を読み取ります。注文が支払い済みとしてマークされるのは、OpenPay が確認した後だけです。決済はこのカートに属し、完了しており、カートの合計金額と通貨に正確に一致している必要があります。その後注文が作成され、お客様には Your card payment has been received. と表示された注文確認ページが表示されます。OpenPay が決済を処理中と報告した場合、注文は Awaiting OpenPay payment で作成され、ページには We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. と表示されます。結果がまだ不明な場合は、Payment confirmation ページに同じテキストと Check again ボタン、Back to checkout ボタンが表示されます。Webhook が届き次第、注文が作成されます。処理中の決済があとで失敗した場合、注文確認ページには Your OpenPay card payment was not completed. Please contact us about this order. と表示されます。

カードが拒否された場合や 3D Secure が失敗した場合、お客様は The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. と表示されたチェックアウトに戻り、再度支払うことができます。カートは保持されます。新しい試行の前に、モジュールはカートの前回の決済を確認します。実際に支払い済みであれば、2 回目の課金なしにその決済から注文が作成されます。処理中であれば、注文は Awaiting OpenPay payment で作成されます。状態を確認できない場合は、新たな課金は行われず、お客様には We could not confirm the status of your previous payment attempt. Please try again in a few minutes. と表示されます。注文が既に存在するカートには、二度と課金されません。

拒否されたカードには、たとえば 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 の技術的なエラーがお客様に表示されることはなく、ログに記録されます。

支払いと確認の間に、カート内のクーポンが無効になった場合は、注文からクーポンが削除されます。お客様は割引価格で支払っているため、注文には備考が付いて OpenPay payment on hold になります。

決済方法が無効な場合、現在のモードのキーが不完全な場合、またはカートの通貨がアカウント国で受け付けられない場合、決済方法はチェックアウトで非表示になります。

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

注文と返金

注文ステータス

注文はまだありません：お客様は 3D Secure ページにいるか、決済を完了していないか、カードが拒否されています。存在するのはカートだけです。

Payment accepted：決済が確認されました。決済は OpenPay の決済 ID をトランザクション ID として記録され、メモには決済 ID とモード（本番またはサンドボックス）が表示されます。

Awaiting OpenPay payment：OpenPay が決済を処理中と報告しています（まだキャプチャされていません）。決済が完了すると Payment accepted に、失敗すると Payment error に移行します。

OpenPay payment on hold：OpenPay が、カートと異なる金額または通貨の完了した決済を報告しました（注文は支払い済みとしてマークされず、メモに差額が表示されます）。クーポンが削除されました。または、既にキャンセルまたは返金された注文に対して決済が届きました（決済は記録されます）。注文を確認して処理するか、OpenPay ダッシュボードで決済を返金してください。

Payment error：処理中の決済が失敗したか、キャンセルされたか、期限切れになりました。

Refunded：モジュールを通じて決済が全額返金されました。

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

OpenPay 決済ブロック

注文ページには OpenPay payment ブロックが表示され、決済 ID、決済ステータス、環境とアカウント国、請求額と注文合計、返金済み金額、サンドボックス決済用の Sandbox バッジ、返金履歴、注文の OpenPay notes が表示されます。

返金

メキシコとペルーのアカウントの場合：OpenPay payment ブロックに金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via OpenPay をクリックします。Refund this amount through OpenPay? This cannot be undone. の確認に同意してください。全額返金と一部返金に対応しており、上限は OpenPay が請求した金額です。注文を編集する権限が必要です。返金は、決済が行われたモードとアカウント国のキーを使って送信されるため、そのモードのキーを設定しておく必要があります。サンドボックスの注文をまだ返金する可能性がある間は、サンドボックスのキーを残しておいてください。OpenPay が返金を受け付けない場合、ブロックにはエラーが表示されます（例：OpenPay refund failed: ...）。この場合、返金は記録されません。返金に成功すると、OpenPay の返金 ID とともに返金履歴とメモに追加されます。全額返金では注文が Refunded になります。一部返金ではステータスは変わりません。返金は OpenPay が決済を確認した後にのみ利用できます。金額の不一致により OpenPay payment on hold になった注文は、モジュールを通じて返金できません。

OpenPay Colombia は、公式の OpenPay プラグインと同様に、API 経由のカード返金に対応していません。コロンビアの決済では、ブロックに返金フォームは表示されません。OpenPay ダッシュボードで決済を返金してください。

モジュールはクレジットノートを作成しません。注文ページの標準的な PrestaShop の返金ボタンでは、OpenPay を通じて返金されません。

OpenPay ダッシュボードで行われた返金とチャージバックは、Webhook で届き、メモに 1 回だけ追加されます。注文ステータスとクレジットノートは自動的には変更されません。必要に応じて手動で更新してください。

ライセンスキー

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

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

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

トラブルシューティング

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

支払いは完了したが注文が作成されていない：お客様が 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 を再試行します。理由を確認するには Debug log をオンにしてください。

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

お客様に The payment could not be processed right now と表示される：OpenPay がリクエストを拒否したか、応答しませんでした。理由はログに記録されています。Merchant ID または秘密鍵の誤りが典型的な原因です。OpenPay が応答しなかった場合は、お客様が再度支払う前に OpenPay ダッシュボードで決済を確認してください。

お客様に This test card cannot be used for real payments と表示される：サンドボックスモードがオフの間に、サンドボックスのテストカードが使用されました。

支払い後に注文が OpenPay payment on hold になる：ブロック内の OpenPay notes を確認し（注文ステータスを参照）、その後注文を処理するか、決済を返金してください。

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

The order is being updated right now で返金が失敗する：Webhook または別のリクエストが同じ時刻に注文を更新していました。しばらくしてから再度試してください。

アンインストール

Modules > Module Manager に進み、VibeFox OpenPay Gateway の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは、常に削除されます。Delete data on uninstall がオンの場合、ゲートウェイの設定、保存された Webhook 検証コード、ログが削除されます。オフの場合、後で再インストールできるようにすべての設定が保持されます。OpenPay の決済記録と返金記録、および注文ステータス Awaiting OpenPay payment と OpenPay payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いメモとトランザクション ID を保持します。

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