VibeFox Tpay for WooCommerce — ヘルプ

要件

WordPress: 5.8 以降。

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

PHP: 8.0 以降。通知の 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. WordPress で Plugins > Add New > Upload Plugin を開き、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_tpay_payment フォルダを /wp-content/plugins/ にアップロードすることもできます。

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

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

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

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

6. Enable/Disable をオンにし、サンドボックスモードで決済をテストしてから、実際の決済を受け付けるために Sandbox mode のチェックを外します。

設定

すべての設定は 1 つのページにあります。WooCommerce > Settings > Payments > Tpay です。サンドボックスモードがオンの間、フィールドの上に Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. と表示されます。このページは、現在のモードのキーが不完全な場合（その場合、Tpay はチェックアウトに表示されません）、ストアの通貨が PLN でない場合、JWS チェックが有効なのに PHP の OpenSSL 拡張機能がない場合（決済が確認されなくなります）に警告を表示します。決済方法の一覧では、現在のモードのキーを入力するまで、Tpay に「設定が必要」と表示されます。Merchant ID や Client ID に貼り付けたスペースは、保存時に削除されます。

一般

Enable/Disable: Enable Tpay payments で決済方法のオンとオフを切り替えます。デフォルト: オフ。

Title: チェックアウトで購入者に表示される決済方法のタイトル。デフォルト: Tpay。

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

Sandbox mode: Use the Tpay sandbox (test payments, no real money)。サンドボックスモードでは、サンドボックスキーと Tpay のサンドボックス API を使用します。本番キーで実際の決済を受け付けるには、オフにします。返金は常に、注文が支払われた環境に送信されます。デフォルト: オン。

本番キー

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

Merchant ID: Tpay アカウント ID（数字）。Tpay はすべての通知にこの ID を含めます。

Client ID: Open API Client ID。

Client secret: Open API Client secret。

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

サンドボックスキー

サンドボックスは、独自のキーを持つ別の 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: サンドボックスアカウントの通知用セキュリティコード。

決済通知

Tpay は、このセクションに表示されるアドレスに決済を確認します。アドレスは次のような形式です: https://your-site/wc-api/wc_tp_payment/。このアドレスは各取引とともに自動的に送信されます。Tpay の管理画面では、セキュリティコード以外に設定する必要はありません。注文が支払い済みになるのは、チェックサムと署名が有効で、金額が一致する通知を受け取った後だけです。Tpay は、貴店が通知を受け入れるまで通知を繰り返します。

JWS 署名: Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended)。PHP の OpenSSL 拡張機能と、secure.tpay.com への外部 HTTPS 通信が必要です。MD5 チェックサムは常に検証されます。デフォルト: オン。

詳細設定

Debug log: Log payment events。技術的なイベントのみを記録します（キーや購入者データは含みません）。記録先は WooCommerce > Status > Logs で、ソースは wcp_tpay_payment です。デフォルト: オフ。

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted。プラグインを無効化しても何も削除されません。注文と、その Tpay 決済データは常に保持されます。デフォルト: オフ。

バージョン 1.0 の設定は自動的に移行されます。テストモードがオンの状態で使用していたキーは、サンドボックスキーになります。

チェックアウト

購入者は決済方法（デフォルトは Tpay）を選択して注文を確定します。サンドボックスモードでは、チェックアウトに Sandbox mode — no real money is charged. と表示されます。プラグインは、注文金額を PLN で指定した Tpay 取引を作成します。説明には Order # と注文番号を使用します。購入者の氏名、メールアドレス、住所、電話番号を送信し、購入者を Tpay の決済ページにリダイレクトします。ページは、サイトの言語に応じてポーランド語、英語、ウクライナ語で表示されます（それ以外の言語では英語になります）。購入者はそのページで BLIK、銀行振込、カード、または貴社の Tpay アカウントで有効になっているその他の方法を選び、支払いを行います。

注文が支払い済みになるのは、Tpay が確認した後だけです。Tpay は貴店に通知を送信します。プラグインは、セキュリティコードによる MD5 チェックサム、Merchant ID、（有効な場合は）JWS 署名を検証し、続いて金額を確認します。金額は、今回の決済の試行で要求された金額および注文合計と等しい必要があり、支払われた金額がそれより少ないことはできません。有効なチェックサムや署名がない通知は拒否されます。

決済後、購入者は注文受付ページに戻ります。戻っただけでは、注文は支払い済みになりません。通知がまだ届いていない場合、ページは取引の状態を Tpay API に問い合わせ（最短 10 秒間隔）、同じ検証を適用します。決済が確認されるまで、ページには 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: と、Pay again リンクが表示されます。Tpay が決済の失敗を報告すると、ページには Tpay reports that the payment did not go through. You can try again: と、同じリンクが表示されます。Tpay のページで決済が失敗すると、Tpay は購入者を同じ注文の Pay for order ページに戻します。

決済の試行ごとに、個別の参照番号があります。購入者が再決済すると、その注文で以前に行われた未払いの Tpay 取引は、Tpay 側でキャンセルされます。以前のリンクから完了した決済は、引き続き受け付けられます。同じキャンセル処理は、未払いの注文がキャンセルされたとき（例: WooCommerce の在庫保持タイムアウト）にも行われます。

Tpay が決済を開始できない場合、購入者には The Tpay payment could not be started. Please try again or choose another payment method. と表示され、理由がログに記録されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の High-Performance Order Storage（HPOS）に対応しています。

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

注文と返金

注文ステータス

Pending payment: Tpay の取引は作成されましたが、決済はまだ確認されていません。注文メモには Tpay の取引と環境が表示されます。

Processing: Tpay が決済を確認しました。これは決済後の WooCommerce の標準ステータスです（ダウンロード可能な仮想商品のみの注文は完了になります）。メモには、決済が通知で確認されたか、ステータス確認で確認されたかが記載され、過払いがあればそれも表示されます。取引 ID は Tpay の取引タイトル（TR-...）です。

On hold: 決済は届きましたが、その金額が要求金額または注文合計と異なる、一部だけが支払われた、または注文がキャンセル済みだった、のいずれかです。注文メモに説明があります。Tpay の管理画面で決済を確認し、注文を完了するか返金してください。

Failed: Tpay が決済の失敗を報告しました。保留中の注文のみ、失敗に変わります。購入者は再決済できます。

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

返金

注文を開き、Refund をクリックし、金額を入力して Refund via Tpay をクリックします（ボタンには貴店の Title が表示されます）。Tpay で決済を受け付けた注文については、全額返金と一部返金に対応しています。未払いの注文では、このボタンは表示されません。返金は、注文が支払われた環境（サンドボックスまたは本番）に送信されるため、その環境のキーを設定しておく必要があります。返金は、Tpay が確認した時点で完了となります。Tpay が拒否した、または確認しなかった返金はエラーとして表示され、WooCommerce には記録されません。返金が成功すると、入力した理由とともに注文メモに追加されます（理由は Tpay に送信されません）。

Tpay の加盟店パネルで行った返金は、WooCommerce に自動では追加されません。

ライセンスキー

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

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

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

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

トラブルシューティング

チェックアウトに Tpay が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの 4 つのキー（Merchant ID、Client ID、Client secret、Security code）がすべて入力されていることを確認してください。ストアの通貨（または Pay for order ページの注文通貨）が PLN であることも確認してください。設定ページには、これらの問題ごとに警告が表示されます。

決済は完了したが、注文が Pending payment のまま: Tpay が通知を届けられなかったか、通知が拒否されました。Debug log をオンにし、WooCommerce > Status > Logs でソースが wcp_tpay_payment のログを確認してください。よくある原因は、現在のモードのセキュリティコードまたは 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 チェックサムは引き続き確認されます。

注文が On hold: 注文メモを確認してください。支払われた金額が注文と一致しなかったか、キャンセル済みの注文に対して決済が届きました。Tpay の管理画面で決済を確認し、注文を完了するか返金してください。

購入者に The Tpay payment could not be started と表示された: 現在のモードのキーが正しくないか、Tpay がリクエストを拒否しました。ログに Tpay のエラーが表示されます。

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

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

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。削除するには、無効化してから Plugins ページで削除してください。このプラグインのライセンスキーとライセンス状態は常に削除されます。キャッシュされた Tpay のアクセストークンと証明書も削除されます。ゲートウェイの設定とログは、Delete data on uninstall がオンの場合のみ削除されます。それ以外の場合は、後で再インストールするために残ります。既存の注文は、決済メモ、Tpay の取引データ、取引 ID を保持します。

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