VibeFox Tpay for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは古い PHP バージョンへのインストールを拒否します。通知の JWS 署名を検証するには、OpenSSL 拡張機能と secure.tpay.com への外向き HTTPS 接続が必要です。

ショップの通貨: ポーランドのズウォティ（PLN）のみ。Tpay は PLN で決済を行い、その Open API には通貨のフィールドがありません。そのため、カートが別の通貨を使用している場合は、決済方法が非表示になります。

ショップへのインターネットアクセス: Tpay は決済通知をショップに送信します。そのため、通知用アドレスはインターネットから到達可能である必要があります（ファイアウォールや HTTP 認証によってブロックされていないこと）。

Tpay アカウント: Tpay 加盟店パネルから次の値が必要です。Merchant ID（Tpay アカウントの ID）、Open API キーの Client ID と Client secret（Integration, API）、およびセキュリティコード（Settings, Notifications）。サンドボックスのキーは、別の Tpay サンドボックスアカウントで取得します。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox Tpay Payment を探し、Configure をクリックすることもできます。

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

4. サンドボックスのキーと本番のキーを入力します（Configuration を参照）。Tpay パネルでは、セキュリティコード以外に設定する必要はありません。通知用アドレスは各取引とともに送信されます。

5. Enable/Disable をオンにして Save をクリックします。サンドボックスモードで決済をテストし、その後 Sandbox mode をオフにして実際の決済を受け付けます。

インストール時に、モジュールは注文ステータス Tpay payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを提供します。Payment > Preferences で制限できます。ただし、このモジュールでは PLN の許可を残しておく必要があります。

Configuration

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Tpay Payment > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。入力欄の上には、サンドボックスモードがオンの間、Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. と表示されます。現在のモードのキーが不完全な場合（その場合、チェックアウトに Tpay は表示されません）、ショップの既定の通貨が PLN でない場合、JWS チェックがオンなのに PHP の OpenSSL 拡張機能がない場合（その場合、決済は確認されません）に警告が表示されます。Merchant ID や Client ID と一緒に貼り付けられた空白は、保存時に削除されます。

Tpay

Enable/Disable: Enable Tpay payments は決済方法を有効または無効にします。既定値：無効。

Title: チェックアウトで購入者に表示される決済方法のタイトルです。注文に保存される決済方法の名前にもなります。既定値：Tpay。必須。

Description: チェックアウトで購入者に表示される決済方法の説明です。既定値：Pay with BLIK, online bank transfer or card on the secure Tpay page.

Sandbox mode: Tpay のサンドボックス（テスト決済、実際の資金は発生しません）を、サンドボックスのキーと openapi.sandbox.tpay.com とともに使用します。本番のキーで実際の決済を受け付けるには、オフにします。返金は常に、注文が支払われた環境に送られます。既定値：オン。

Production keys

場所：Tpay 加盟店パネルの Integration, API（Open API キー：Client ID と Secret）。Merchant ID は Tpay アカウントの ID です。セキュリティコードは Settings, Notifications にあります。

Merchant ID: Tpay アカウントの ID（数字）。Tpay は各通知でこの値を送信します。

Client ID: Open API の Client ID。

Client secret: Open API の Client secret。

Security code: Tpay 通知の MD5 チェックサムを検証するために使用します。

Sandbox keys

サンドボックスは、独自のキーを持つ別の Tpay テストアカウントです（Tpay API のドキュメントを参照）。Sandbox mode がオンの間のみ使用されます。

Sandbox Merchant ID: サンドボックスアカウントの Merchant ID。

Sandbox Client ID: サンドボックスアカウントの Open API Client ID。

Sandbox Client secret: サンドボックスアカウントの Open API Client secret。

Sandbox Security code: サンドボックスアカウントの通知用セキュリティコード。

保存されたシークレット（両環境の Client secret と Security code）は、再び表示されることはありません。入力欄は空のままで、Saved - leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。

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

Payment notifications

Notification URL: Tpay は、ここに表示されるアドレスに決済を通知します。フレンドリー URL の場合、https://your-shop/module/wcp_tpay_payment/notify のような形式になります（/en/ のような言語コードが含まれる場合もあります）。このアドレスは各取引で自動的に送信されるため、Tpay パネルではセキュリティコード以外に何も設定する必要はありません。注文は、有効なチェックサムと署名があり、金額が一致する通知を受け取った後（または購入者が戻った際に一致する状態確認を行った後）にのみ作成されます。Tpay は、ショップが受け付けるまで通知を再送します。

JWS signature: Tpay の証明書を使用して、通知の X-JWS-Signature も検証します（推奨）。PHP の OpenSSL 拡張機能と secure.tpay.com への外向き HTTPS 接続が必要です。証明書は 1 日間キャッシュされます。MD5 チェックサムは常に検証されます。既定値：オン。

Advanced

Debug log: 決済イベントを記録します。記録されるのは技術的なイベントのみ（キーや購入者のデータは含みません）で、モジュールフォルダ内の logs/wc_tp_debug.log.php に保存されます。このファイルは Web から開くことはできません。既定値：無効。無効の間は、エラーを含め何も記録されないため、問題の原因を調べる前に有効にしてください。

Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが消去されます。

Delete data on uninstall: オンの場合、モジュールをアンインストールするとモジュールの設定とログが削除されます。注文と Tpay の決済データは常に保持されます。既定値：無効。

購入手続き

決済の段階で、購入者は決済方法を選択します（既定値は Tpay）。サンドボックスモードでは、決済オプションに Sandbox mode - no real money is charged. と表示されます。確定後、モジュールはカートの合計額について、PLN で Tpay の取引を作成します。説明は Cart # とカート番号です。購入者の氏名、メールアドレス、請求先住所、電話番号を渡し、購入者を Tpay の決済ページに移動させます。ページは、ショップの言語に応じてポーランド語、英語、ウクライナ語で表示されます（その他の言語の場合は英語）。購入者はそこで BLIK、銀行振込、カード、またはご自身の Tpay アカウントで有効になっているその他の方法を選び、支払いを行います。この時点では、まだ注文は存在しません。

注文は、Tpay が確認した後にのみ支払い済みとしてマークされます。Tpay はショップに通知を送信します。モジュールは、決済を開始した環境のキーを使用して、セキュリティコードによる MD5 チェックサム、Merchant ID、（オンの場合）JWS 署名を検証します。その後、金額を確認します。金額は、この決済の試行で要求された金額およびカート合計と等しくなければならず、支払われた金額はそれより少なくてはなりません。有効なチェックサムまたは署名のない通知は拒否されます。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。

支払い後、購入者はショップに戻ります。戻っただけでは、何も支払い済みにはなりません。通知がまだ届いていない場合、モジュールは Tpay API に取引の状態を問い合わせ（最大 10 秒ごと）、同じ検証を適用します。決済が確認されるまで、Payment confirmation ページに Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again: と表示され、Refresh ボタンと、チェックアウトに戻る Pay again ボタンが表示されます。通知が届くとすぐに注文が作成されます。

Tpay が決済の失敗を報告した場合、購入者は Tpay reports that the payment did not go through. Please try again or choose another payment method. と表示されたチェックアウトに戻ります。Tpay のページで決済が失敗した場合も、Tpay は購入者をチェックアウトページに戻します。どちらの場合も、カートは保持されます。注文が保留になった場合、確認ページには Your payment is being verified. We will contact you as soon as it is confirmed. と表示されます。

決済の試行ごとに、個別の参照番号があります。購入者が再度支払うと、そのカートの以前の未払いの Tpay 取引は Tpay でキャンセルされます。以前のリンクですでに完了した決済は、引き続き受け付けられます。カートにすでに注文がある場合、購入者は新しい決済ではなく、その注文の確認ページに移動します。

Tpay が決済を開始できない場合、購入者はチェックアウトに留まり、The Tpay payment could not be started. Please try again or choose another payment method. と表示されます。理由はログに記録されます（Debug log がオンの場合）。

通知用アドレスは、ショップがメンテナンスモードの間も機能し、ショップの国による制限によってブロックされることはありません。

このモジュールは PLN のみに対応しています。ショップには、銀行や BLIK コードを選択する機能はありません（購入者は Tpay のページで選択します）。保存済みカード、サブスクリプション、ショップ内の Apple Pay や Google Pay のボタン、分割払いの計算機もありません。

注文と返金

注文ステータス

No order yet: 購入者は Tpay に移動しましたが、まだ支払っていないか、Tpay がまだ決済を確認していません。カートだけが存在します。決済に失敗した場合も、注文は作成されません。

Payment accepted: Tpay が決済を確認しました。決済は、取引 ID として Tpay の取引タイトル（TR-...）とともに記録されます。メモには、通知で確認されたか状態確認で確認されたか、環境、そして過払いがあればその内容が示されます。

Tpay payment on hold: 決済は届きましたが、その金額が要求された金額またはカート合計と異なっています（例：決済の開始後にカートが変更された）。一部のみが支払われた、または注文がキャンセルされた後に決済が届いた、といった場合もあります。メモに詳細が記載されます。Tpay パネルで決済を確認してから、注文を処理するか返金してください。購入者が新しい試行で正しい金額を支払った場合、注文は Payment accepted に移動します。

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

Tpay が、すでに支払い済みまたは返金済みの注文について別の決済を報告した場合、注文は変更されません。必要に応じて、余分な決済を Tpay パネルで返金するようメモで通知されます。Tpay が報告したチャージバックは、メモとして追加されます。

Tpay 決済ブロック

注文ページには、Tpay payment ブロックが表示されます。このブロックには、Tpay の取引タイトルと ID、決済の参照番号（CRC）、環境（サンドボックスの決済には Sandbox バッジが付きます）、決済の状態と確認方法、支払われた金額、注文合計と返金額、返金履歴、カートのすべての Payment attempts、そして注文の Payment notes が含まれます。

返金

Tpay payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Tpay をクリックします。Refund this amount through Tpay? This cannot be undone. の確認に応じてください。Tpay で決済を受け取った注文については、保留中の注文を含め、全額返金と一部返金に対応しています。注文を編集する権限が必要です。Modules ページへのアクセス権は不要です。返金できるのは、支払いを行った Tpay 取引が受け取った金額までで、注文合計を超えることはできません。一部の支払いや変更されたカートの後は、ブロックに Refundable (paid through Tpay) と表示されます。返金は、注文が支払われた環境（サンドボックスまたは本番）に送られるため、その環境のキーが設定されている必要があります。返金は、Tpay が確認した場合にのみ完了とみなされます。Tpay が拒否した、または確認しなかった返金はエラーとして表示され、記録されません。成功した返金は、入力された理由とともに返金履歴とメモに追加されます（理由は Tpay には送信されません）。返金可能な全額を返金すると、注文は Refunded になります。一部返金では、ステータスは変わりません。

このモジュールは貸方票（credit slip）を作成しません。注文ページの標準の PrestaShop の返金ボタンでは、Tpay を通じて返金されません。Tpay 加盟店パネルで行われた返金は、PrestaShop に自動的には追加されません。

ライセンスキー

このモジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Tpay Payment は Modules > Module Manager > VibeFox Tpay Payment > Configure ページの最上部にあり、設定の上に表示されます。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ボタンが表示されます。ボタンは、Check now でステータスを再確認、Change key で別のキーを入力、Remove key でこのショップからキーを削除します。その下には Product: presta-payment-tpay の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。モジュールの Configure 権限を持つ従業員のみがキーを変更できます。ブロックの文言は管理画面の言語に従います（英語とロシア語が含まれます）。

キーが受け付けられない場合、ブロックにその理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、License expired on（日付付き）。ショップのアドレスを変更した後、またはアカウントでドメイン枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスで動作を続けます。

1 つのキーは 1 つのドメインで使用できます。メインショップのドメインで、マルチストア構成の場合も同様です。ショップからキーを削除しても、ドメイン枠は解放されません。vibefox.net のアカウントで枠を解放してください。

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

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

トラブルシューティング

チェックアウトに Tpay が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの 4 つのキーがすべて入力されていること（Merchant ID、Client ID、Client secret、Security code）を確認してください。カートの通貨が PLN であること、Payment > Preferences で、PLN、購入者の国、購入者のグループに対してモジュールが許可されていることを確認してください。設定ページには、キーが不足している場合や、ショップの通貨が PLN でない場合に警告が表示されます。

決済は完了したが、注文が作成されなかった: Tpay が通知を配信できなかった、または通知が拒否されました。Debug log をオンにして、モジュールのページにある Log 欄を確認してください。よくある原因は、決済の環境に対して間違ったセキュリティコードまたは Merchant ID が使われている、通知用アドレスがブロックされている（ファイアウォール、HTTP 認証）、または JWS 検証に必要な OpenSSL や外向き HTTPS がサーバーにないことです。購入者が支払い後にショップに戻った場合も、注文は作成されます。

Notification answered FALSE - invalid checksum: 設定の Merchant ID またはセキュリティコードが、決済の Tpay アカウント（サンドボックスまたは本番）と一致していません。

Notification answered FALSE - invalid JWS signature: 署名を検証できませんでした。たとえば、OpenSSL がない、または Tpay の証明書をダウンロードできない場合です。サーバーを修正するか、必要に応じて JWS signature をオフにしてください。MD5 チェックサムは引き続き検証されます。

Notification answered FALSE - busy, retry later or FALSE - order could not be created: カートが同時に別のリクエストによって処理されていた、または注文を作成できませんでした（たとえば、モジュールが無効になっている場合）。Tpay は通知を自動的に再送します。理由を確認するには Debug log をオンにしてください。

通知 URL に FALSE - POST only in the browser と表示される: これは正常です。この URL は Tpay からの通知のみを受け付けます。

注文が Tpay payment on hold になっている: Tpay payment ブロックのメモを読み（注文ステータスを参照）、Tpay パネルで決済を確認してから、注文を処理するか決済を返金してください。

購入者に The Tpay payment could not be started と表示された: 現在のモードのキーが間違っているか、Tpay がリクエストを拒否しました。Debug log をオンにしてください。ログに Tpay のエラーが表示されます。

購入者に We could not match this payment to an order と表示された: 戻りリンクが購入者のカートのものではありませんでした。購入者に請求が行われていた場合でも、通知によって注文は作成されます。Tpay パネルを確認してください。

返金に失敗する: メッセージにキーがないと書かれている場合は、注文が支払われた環境のキーを入力してください。金額が多すぎるというメッセージの場合は、表示された金額までしか返金できません。Tpay が返金を確認しなかった場合は、再試行する前に Tpay 加盟店パネルで取引を確認してください。

アンインストール

Modules > Module Manager に移動し、VibeFox Tpay Payment の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。キャッシュされた Tpay のアクセストークンと証明書は、常に削除されます。Delete data on uninstall がオンの場合は、モジュールの設定とログも削除されます。オフの場合は、後で再インストールできるように設定が保持されます。Tpay の取引と返金、および Tpay payment on hold の注文ステータスは常に保持されるため、以前に支払われた注文は、再インストール後も返金できます。既存の注文は、決済メモと取引 ID を保持します。

Tpay は、その所有者の商標です。このモジュールは Tpay と提携しておらず、Tpay による承認も受けていません。