VibeFox HyperPay for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 8.0 以降。インストールされ、有効であること。WooCommerce がないとプラグインは有効化できません。

PHP: 8.0 以降。

HyperPay アカウント: HyperPay は、加盟店アカウントの設定時に Access Token と Entity ID を発行します。テスト用と本番用の認証情報は別々です。また、HyperPay の管理画面で支払い用ウェブフックを追加し、その復号キー（webhook key）を用意する必要があります。キーは Administration > Webhooks に表示されます（「設定」を参照）。

カード情報: カードは HyperPay のウィジェットにのみ入力されるため、カード情報が貴店のサーバーに届くことはありません（PCI DSS SAQ A）。

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

インストール

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

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

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

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

5. HyperPay から発行されたテスト用の Access Token、Entity ID、ウェブフックキーを入力し、Test Mode をオンのままにします。

6. HyperPay の管理画面（Administration > Webhooks）で、設定に表示された URL を使って支払い用ウェブフックを追加し、その復号キーを同じモードのウェブフックキー欄にコピーします。

7. Enable/Disable をオンにし、HyperPay のテストカードでテスト決済を行います。その後、本番の認証情報を入力し、Test Mode をオフにします。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > HyperPay。テストモードがオンの間、フィールドの上に テストモードがオンです：支払いは HyperPay のテストシステムに送信され、実際の料金は請求されません。 と表示されます。現在のモードの Access Token または Entity ID が未入力の場合（その場合、この支払い方法はチェックアウトに表示されません）、また現在のモードに有効なウェブフックキーがない場合（その場合、支払いは購入者がストアに戻った後にのみ確認されます）には警告が表示されます。支払い方法の一覧では、現在のモードに Access Token と Entity ID が設定されるまで、このゲートウェイは「設定が必要」と表示されます。保存時には認証情報から空白が削除され、ウェブフックキーが 64 文字の 16 進数キーでない場合はエラーが表示されます。

Enable/Disable: Enable HyperPay Payment で、この支払い方法のオン/オフを切り替えます。既定値: オフ。

Title: チェックアウト時に購入者に表示されるタイトル。既定値: Credit/Debit Card (HyperPay)。

Description: チェックアウト時に購入者に表示される説明。既定値: Pay securely using your credit or debit card。

API 認証情報

Access Token、Entity ID、ウェブフックキーは、加盟店アカウントの設定時に HyperPay から発行されます。テスト用と本番用の認証情報は別々です。ウェブフックキーは HyperPay の管理画面の Administration > Webhooks に表示されます。

Test Mode: Enable Test Mode は、HyperPay のテストシステム（eu-test.oppwa.com）とテスト用認証情報を使用します。実際の料金は請求されません。オフにすると、本番用認証情報（eu-prod.oppwa.com）で実際の支払いを受け付けます。既定値: オン。

Test Access Token: HyperPay テストアカウントの bearer トークン。

Test Entity ID: テスト用決済チャネルの Entity ID。

Test Webhook Key: テストシステムのウェブフック通知を復号するための、64 文字の 16 進数キー。

Live Access Token: HyperPay 本番アカウントの bearer トークン。

Live Entity ID: 本番用決済チャネルの Entity ID。

Live Webhook Key: 本番システムのウェブフック通知を復号するための、64 文字の 16 進数キー。

Webhook

ウェブフックは、購入者がストアに戻る前にブラウザを閉じた場合でも、支払いの情報をストアに通知します。HyperPay の管理画面（Administration > Webhooks）で、設定のこのセクションに表示された URL を使って、支払い用のウェブフックを追加します。URL は次の形式です：https://your-site/wp-json/hyperpay-p/v1/webhook。次に、ウェブフックの復号キーを同じモードの Test Webhook Key または Live Webhook Key にコピーします。

HyperPay のウェブフックは暗号化されています（AES-256-GCM）。お使いのキーで復号できないウェブフックは拒否されます。処理されるのは支払い通知のみで、その支払いは、通知を復号したキーと同じモードで作成された、貴店の注文の決済セッションに属している必要があります。HyperPay のテスト通知は確認応答されます。ウェブフックは、HyperPay の管理画面で行われたキャプチャ、リバーサル、返金、チャージバックも通知します（「注文と返金」を参照）。ウェブフックがない場合、支払いは購入者が支払い後にストアへ戻ったときにのみ確認されます。

支払い

Transaction Type: カードへの請求方法。

Payment Brands: 支払いウィジェットに表示されるブランド: VISA、Mastercard、mada、American Express、STC Pay、Apple Pay。既定値: VISA と Mastercard。HyperPay があなたの Entity ID で有効にしたブランドだけを選んでください。mada、STC Pay、Apple Pay は多くの場合独自のエンティティを使用するため、このプラグインではサポートされません。

詳細設定

Enable Logging: Log API requests and responses。デバッグ情報は WooCommerce > Status > Logs に、ソース wcp_hyperpay_payment_gateway として書き込まれます。エラーは常に記録されます。ログにはカード情報、キー、購入者データは含まれません。既定値: オフ。

Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled。プラグインを削除したときに、設定とログファイルを削除します。注文に保存された HyperPay のデータは残ります。既定値: オフ。

チェックアウト

購入者は支払い方法（既定では Credit/Debit Card (HyperPay)）を選び、Continue to payment をクリックします。注文が作成され、購入者は Pay for order ページに移動します。そこでプラグインは、注文金額と注文通貨で HyperPay の決済セッションを準備し、以下で支払いを完了してください： という文言とともに HyperPay ウィジェットを表示します。HyperPay が対応している場合、ウィジェットはサイトの言語を使用します。テストモードでは、ページに テストモード: HyperPay のテストカードを使用してください。実際の支払いは行われません。 と表示されます。購入者はウィジェットにカード情報を入力します。

支払い後、購入者は貴店に戻ります。プラグインは、支払いがこの注文の決済セッションに属していることを確認し、サーバー間リクエストで HyperPay に結果を照会します。注文が支払い済みになるのは、HyperPay が確認した後（そのリクエストまたはウェブフックによる）だけです。金額と通貨は注文と一致している必要があります。戻りとウェブフックが同時に届いた場合は順番に処理されるため、注文が二重に処理されることはありません。支払いが確認されると、購入者は注文受付ページに移動します。

支払いが完了しなかった場合、購入者は Pay for order ページに戻り、次のメッセージが表示されます：支払いに失敗しました： と HyperPay からの理由、支払いが完了しませんでした。もう一度お試しください。、または まだ支払いを確認できていません。料金が請求されている場合は、注文が自動的に更新されます。そうでない場合は、もう一度お試しください。。購入者は同じページで再度支払えます。ウィジェットを準備できない場合、購入者には短いメッセージ（例：一部の請求情報が決済プロバイダーに受け付けられなかったこと）と Try Again ボタンが表示されます。詳細は注文メモに追加されます。

金額は HyperPay API の要件に従って小数点以下 2 桁で送信されます。小数点以下 3 桁の通貨（KWD、BHD、JOD、OMR）の場合、注文金額は小数点以下 2 桁に丸められます。

この支払い方法は、クラシックチェックアウト、カートとチェックアウトのブロック、および Pay for order ページで動作します。テストモードでは、チェックアウトブロックに テストモード: 実際の支払いは行われません。 と表示されます。WooCommerce の高パフォーマンス注文保存（HPOS）に対応しています。

本プラグインは、WooCommerce からの返金や取り消し、カードの保存やトークン化、サブスクリプション、Apple Pay のドメイン認証、ブランドごとの個別 Entity ID には対応していません。また、Tabby、Tamara などの後払い（buy now, pay later）方式にも対応していません。

注文と返金

注文ステータス

Pending payment: 購入者がまだ支払っていない、ウィジェットでの操作を完了していない、または HyperPay がまだ支払いを確認していない状態です。

Processing: 即時決済が確認された、または事前承認がキャプチャされた状態です。仮想のダウンロード可能商品のみの注文は、WooCommerce の既定どおり「完了」になります。注文メモには HyperPay の結果コード、説明、支払い ID が表示されます。取引 ID は HyperPay の支払い ID です。HyperPay がその支払いを手動審査の対象にした場合、メモにその旨が表示されます。発送前に HyperPay の管理画面で確認してください。

On hold (pre-authorization): 金額は確保されています。注文アクション Capture HyperPay payment または HyperPay の管理画面でキャプチャしてください。その後、キャプチャのウェブフックによって注文が完了します。

On hold after payment: HyperPay が注文と異なる金額または通貨を報告した（例：支払いページを開いた後に注文が編集された）、支払いが HyperPay でまだ保留中である、または注文がキャンセルされた後に支払いが届いた状態です。注文メモに理由が記載されます。HyperPay の管理画面で支払いを確認し、完了させるか返金してください。

Failed: HyperPay が支払いを拒否しました。理由は注文メモに記載され、購入者にも表示されます。拒否された試行が、支払い済み、確保済み、保留中、またはキャンセル済みの注文を変更することはありません。

Cancelled: 事前承認が HyperPay の管理画面でリバースされ、リバーサルのウェブフックが保留中の注文をキャンセルします。

支払い済みの注文に別の成功した支払いが届いた場合、注文は変更されません。注文メモには、重複した支払いを HyperPay の管理画面で返金するよう指示が表示されます。返金済みの注文に成功した支払いが届いた場合は、メモが追加されるだけです。

キャプチャ

注文アクション Capture HyperPay payment は、まだキャプチャされていない事前承認を持つ保留中の注文に表示されます。WooCommerce に記録済みの返金を差し引いた現在の注文合計を、事前承認を行ったモードでキャプチャします。キャプチャに成功すると、注文は Processing になります。HyperPay がキャプチャを拒否した場合、結果コードと説明が表示され、注文メモに追加されます。事前承認のリバース（取り消し）は、HyperPay の管理画面で行います。

返金

WooCommerce からの返金はサポートされていません。HyperPay の管理画面で支払いを返金し、WooCommerce では Refund manually で記録してください。HyperPay で行われた返金とチャージバックは、ウェブフックによって注文にメモとして追加されます。注文ステータスは変わりません。

ライセンスキー

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

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

有効なキーがない場合、チェックアウトで購入者に HyperPay は表示されません。それでも支払いが開始された場合、購入者には この支払い方法は利用できません。別の方法をお選びください。 と表示されます。ログイン中のストア管理者には、(unlicensed — visible to admins only) と表示された状態で支払い方法が表示され続けるため、キーを購入する前にプラグインの設定とテストができます。プラグインの一覧ページと WooCommerce のページには通知が表示されます。既存の注文には影響しません。開始済みの支払いは引き続き確認され、キャプチャも機能します。

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

トラブルシューティング

HyperPay がチェックアウトに表示されない: ライセンスが有効か、Enable/Disable がオンか、現在のモードに Access Token と Entity ID（テストモードではテスト用、本番モードでは本番用）があるかを確認してください。設定ページに、これらが不足している場合の警告が表示されます。

支払いは完了したのに、注文が Pending payment のまま: ウェブフックが機能しておらず、購入者がストアに戻っていません。HyperPay の管理画面で、使用しているモードの支払い用ウェブフックが存在すること、その URL が設定に表示されたものと完全に一致すること、そして復号キーが同じモードのウェブフックキー欄に入っていることを確認してください。WooCommerce > Status > Logs でソース wcp_hyperpay_payment_gateway を確認してください。

ウェブフックが Decryption failed を返す: ウェブフックキーが別のウェブフックまたは別のモードのものです。HyperPay の管理画面からキーを再度コピーしてください。

ウェブフックが Webhook key not configured を返す: 有効なウェブフックキーが設定されていません。64 文字のキーを設定に貼り付けてください。HyperPay はウェブフックを再試行します。

ログに Webhook ignored と表示される: この支払いは、このストアの注文に属していないか、別のモードで行われたものです。テストの支払いと本番の支払いは分けて扱われます。

支払いフォームが読み込まれない: 注文メモを確認してください。設定エラーは通常、現在のモードの Access Token または Entity ID が間違っていることを意味します。請求情報に関するメッセージは、HyperPay が一部の購入者データを受け付けなかったことを意味します。選択した Payment Brands が、あなたの Entity ID で有効になっていることを確認してください。

注文が On hold で、金額/通貨の不一致のメモがある: HyperPay が、注文合計や通貨と一致しない支払いを報告しました（例：支払いページを開いた後に注文が編集された）。HyperPay の管理画面で支払いを確認し、完了させるか返金してください。

キャプチャに失敗する: 注文メモの結果コードと説明を確認してください。キャプチャは事前承認のモードで送信されるため、そのモードの認証情報が設定されている必要があります。

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

開発者向け: フィルター hyperpay_p_icon で、支払い方法のアイコンを変更できます。

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。削除するには、無効化してから Plugins ページで削除してください。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定、プラグインの一時データ、ログファイルは、Delete Data on Uninstall がオンの場合にのみ削除されます。それ以外の場合は、後で再インストールするために残ります。注文に保存された HyperPay のデータは、常に保持されます。既存の注文は、支払いメモとトランザクション ID を保持します。

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