VibeFox HyperPay for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: OpenSSL 拡張を備えた 8.0 以降（ウェブフックの復号に使用されます）。拡張機能がない場合、モジュールはインストールできません。

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

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

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

インストール

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

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

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

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

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

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

インストール時に、モジュールは 3 つの注文ステータスを作成します：Awaiting HyperPay payment、HyperPay payment authorized、HyperPay payment on hold。PrestaShop は新しい決済モジュールを、その時点で有効になっている通貨、国、顧客グループに関連付けます。後から有効にした国は、Payment > Preferences で許可する必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。テストモードがオンの間、ページは入力欄の上に Test mode is on: payments go to the HyperPay test system and no real money is charged. と表示します。現在のモードの Access Token または Entity ID が未入力の場合は警告されます（この場合、チェックアウトに決済方法は表示されません）。また、現在のモードに有効なウェブフックキーがない場合も警告されます（この場合、支払いは購入者がストアに戻ったときにのみ確認されます）。保存時に認証情報から空白が取り除かれ、ウェブフックキーが 64 桁の 16 進数キーでない場合はページが警告します。

HyperPay

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: HyperPay のテストシステム（eu-test.oppwa.com）とテスト用認証情報を使用します。実際の代金は請求されません。本番用認証情報（eu-prod.oppwa.com）で実際の支払いを受け付けるにはオフにします。初期値：オン。オンの間、購入者には決済方法の下に Test mode: no real payment will be made. と表示されます。

Test Access Token: HyperPay テストアカウントの bearer token です。

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

Test Webhook Key: テストシステムのウェブフック通知の復号に使用する 64 桁の 16 進数キーです。

Live Access Token: HyperPay 本番アカウントの bearer token です。

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

Live Webhook Key: 本番システムのウェブフック通知の復号に使用する 64 桁の 16 進数キーです。

保存済みの access token とウェブフックキーは再表示されません。入力欄は空のままとなり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

保存済みのシークレットを削除: トークンまたはキーにチェックを入れて Save をクリックすると削除されます。入力欄が空の場合は、保存済みの値が保持されます。

Webhook

ウェブフックは、購入者がストアに戻る前にブラウザを閉じた場合でも、支払い情報をストアに伝えます。HyperPay の管理画面（Administration > Webhooks）で、このセクションの Webhook URL に表示された URL を使って支払い用ウェブフックを追加します。フレンドリー URL の場合、https://your-shop/module/wcp_hyperpay_payment_gateway/webhook のような形になり、/en/ のような言語コードが付くこともあります。URL は設定画面に表示されたとおりに正確にコピーしてください。その後、ウェブフックの復号キーを同じモードの Test Webhook Key または Live Webhook Key にコピーします。

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

Payment

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

Payment Brands: 決済ウィジェットに表示されるブランドです：VISA、Mastercard、mada、American Express、STC Pay、Apple Pay。初期値：VISA と Mastercard。どのブランドも選択されていない場合、ページは警告し、ウィジェットには VISA と Mastercard が表示されます。貴社の Entity ID で HyperPay が有効にしたブランドのみを選択してください。mada、STC Pay、Apple Pay は多くの場合独自のエンティティを使用しており、本モジュールはそれに対応していません。

Advanced

Enable Logging: API のリクエストとレスポンスを、モジュールフォルダ内の logs/hyperpay_p_debug.log.php に記録します。このファイルはウェブから開くことはできません。エラーと警告は常に記録されます。ログにはカード情報、キー、購入者データは含まれません。初期値：オフ。

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

Delete Data on Uninstall: オンの場合、モジュールをアンインストールすると、設定、HyperPay の支払い試行のテーブル、ログファイルが削除されます。注文とモジュールの注文ステータスは保持されます。初期値：オフ。

チェックアウト

支払いの段階で購入者は決済方法（初期値は Credit/Debit Card (HyperPay)）を選び、注文を確定します。モジュールは、カードの合計金額とカートの通貨で HyperPay の決済セッションを準備し、HyperPay ウィジェットと Please complete your payment below: のメッセージを含む、ストアの HyperPay payment ページを開きます。ウィジェットは、HyperPay が対応している場合、購入者の言語を使用します。テストモードでは、ページに Test mode: use a HyperPay test card, no real payment will be made. と表示されます。購入者はウィジェットにカード情報を入力するか、Choose another payment method をたどってチェックアウトに戻ります。この時点ではまだ注文は存在しません。カートが変更されない限り、ページを再読み込みすると、最大 25 分間は同じ決済セッションが再利用されます。

支払い後、購入者はストアに戻ります。モジュールは、支払いがこのカートの決済セッションのいずれかに属しているかを確認し、決済セッションを作成したモードで、サーバー間リクエストにより HyperPay に結果を照会します。注文は、HyperPay がこのリクエストまたはウェブフックによって確認した後にのみ、支払い済みとしてマークされます。金額と通貨はカートと一致している必要があります。戻りとウェブフックが同時に届いた場合は、順番に処理されるため、注文が 2 回作成されることはありません。支払いが確認されると注文が作成され、購入者には標準の注文確認ページが表示されます。

支払いが完了しなかった場合、購入者はメッセージとともにチェックアウトに戻ります：Payment failed: と HyperPay が示した理由、Payment was not completed. Please try again.、または We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. カートは保持され、購入者は再度支払うことができます。新しい試行ごとに新しい HyperPay 決済セッションが発行されます。支払いフォームを準備できない場合、購入者は短いメッセージとともにチェックアウトに留まります。たとえば、一部の請求情報が決済プロバイダーに受け付けられなかったことや、決済設定のエラーにより支払いフォームが利用できないことなどが表示されます。技術的な理由はログに記録されます。

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

ストアがメンテナンスモードの間もウェブフックは動作し、ストアの国による制限の影響も受けません。

本モジュールは、PrestaShop からの返金や取り消し、カードの保存やトークン化、サブスクリプション、Apple Pay のドメイン認証、ブランドごとの個別 Entity ID、Tabby、Tamara、その他の後払い方式には対応していません。

注文と返金

注文ステータス

No order yet: 購入者は決済ページに移動しましたが、まだ支払っていない、支払いが拒否された、または HyperPay がまだ支払いを確認していない状態です。カートだけが存在します。

Payment accepted: 即時決済の支払いが確認されたか、事前承認がキャプチャされました。支払いは HyperPay の支払い ID を取引 ID として記録され、非公開のメモに HyperPay の結果コード、説明、支払い ID が表示されます。HyperPay が支払いを手動レビュー対象としてマークした場合、メモにその旨が記載されます。発送の前に HyperPay の管理画面で確認してください。

HyperPay payment authorized: 事前承認によって金額が確保されています。注文の HyperPay ブロックまたは HyperPay の管理画面でキャプチャしてください。キャプチャのウェブフックにより、注文は Payment accepted に移行します。

Awaiting HyperPay payment: HyperPay は支払いを保留中と報告しました。HyperPay が支払いを確認すると、注文は Payment accepted に移行します。

HyperPay payment on hold: HyperPay が、カートまたは注文とは異なる金額または通貨を報告しました（たとえば、決済ページを開いた後にカートが変更された場合）。または、注文がキャンセルされた後に支払いが届きました。メモに理由が記載されています。HyperPay の管理画面で支払いを確認してから、注文を処理するか、支払いを返金してください。

Canceled: 事前承認が HyperPay の管理画面で取り消され、リバーサルのウェブフックによって承認済みの注文がキャンセルされました。

拒否された結果が、既存の注文を変更することはありません。すでに支払い済みの注文に対して別の成功した支払いが届いた場合、注文は変更されません。メモで、HyperPay の管理画面で重複分を返金するよう求められます。返金済みの注文に対する成功した支払いは、メモが追加されるだけです。

HyperPay 支払いブロック

注文ページには HyperPay payment ブロックが表示されます。このブロックには、支払い ID（キャプチャ後はキャプチャ ID も）、取引の種類、決済セッション ID、加盟店取引 ID、HyperPay に送信された金額、結果、テスト支払い用の Test mode バッジが含まれます。モジュールのメモは、注文の非公開メッセージに記録されます。

キャプチャ

HyperPay payment authorized の注文の場合、ブロックには金額とともに Capture payment が表示されます。クリックして Capture the pre-authorized amount through HyperPay? を確認してください。事前承認が行われたモードで、現在の注文合計がキャプチャされます。そのため、そのモードの Access Token と Entity ID が設定されている必要があります。注文を編集する権限が必要ですが、モジュールのページへのアクセスは必要ありません。キャプチャが成功すると、注文は Payment accepted になり、キャプチャ ID が支払いとメモに追加されます。HyperPay がキャプチャを拒否した場合は、結果コードと説明が表示され、メモに追加されます。注文は承認済みのままです。ダブルクリックで 2 回キャプチャされることはありません。事前承認の取り消し（void）は HyperPay の管理画面で行います。

返金

PrestaShop からの返金はサポートされておらず、PrestaShop の標準の返金ボタンでは HyperPay を通じて返金されません。HyperPay の管理画面で支払いを返金し、必要に応じて PrestaShop で部分返金またはクレジットスリップとして記録してください。HyperPay で行われた返金とチャージバックは、ウェブフックによって注文にメモとして追加されます。注文ステータスは変更されません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに HyperPay が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに Access Token と Entity ID が設定されていることを確認してください。テストモードではテスト用、本番モードでは本番用の認証情報が必要です。不足している場合は、設定ページに警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループで許可されているか確認してください。

支払いは完了したが、注文が作成されていない: ウェブフックが機能しておらず、購入者がストアに戻っていません。HyperPay の管理画面で、使用しているモードの支払い用ウェブフックが存在すること、その URL が Webhook URL に表示されたものと正確に一致すること、復号キーが同じモードのウェブフックキーの欄に入っていることを確認してください。Enable Logging をオンにして、モジュールのページにある Log 欄を確認してください。

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

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

ウェブフックが Busy, retry later と応答する: 同じタイミングで別のリクエストが注文を処理していたか、注文を作成できませんでした（たとえば、モジュールが無効になっている場合）。HyperPay はウェブフックを再試行します。理由はログに記録されています。

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

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

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

注文が HyperPay payment on hold になっている: 注文のメモを確認し（注文ステータスを参照）、HyperPay の管理画面で支払いを確認してから、注文を処理するか支払いを返金してください。

キャプチャに失敗する: ブロックとメモに表示された結果コードと説明を確認してください。キャプチャは事前承認と同じモードで送信されるため、そのモードの認証情報が設定されている必要があります。設定されていない場合、ブロックにはそのモードの Access Token / Entity ID が空であることが表示されます。

アンインストール

Modules > Module Manager に移動し、VibeFox HyperPay Payment Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete Data on Uninstall がオンの場合、設定、HyperPay の支払い試行のテーブル、ログファイルが削除されます。オフの場合は、後で再インストールできるようにすべて保持されます。注文ステータス Awaiting HyperPay payment、HyperPay payment authorized、HyperPay payment on hold は常に保持されます。既存の注文は、支払いのメモと取引 ID を保持します。

HyperPay は各所有者の商標です。本モジュールは HyperPay と提携しておらず、HyperPay による推奨も受けていません。