VibeFox TrustPay for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

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

PHP: 8.0 以降。

finby（TrustPay）アカウント: finby Merchant Portal でプロジェクトを作成し、その Project ID と Secret key を用意する必要があります。テスト決済には、別途テスト（playground）プロジェクトが必要で、その Project ID と Secret key も必要です。他のキーは不要です。Secret key は、API アクセスの取得と、決済通知の署名の検証の両方に使われます。

通知 URL に到達できること: finby がインターネット経由で貴サイトにアクセスできる必要があります。ファイアウォール、メンテナンスモード、サイトのパスワード保護があると、決済通知がブロックされます。

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

インストール

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

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

3. 設定を開きます。WooCommerce > Settings > Payments > TrustPay / finby に進むか、Plugins ページでプラグイン名の下の Settings をクリックします。

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

5. 本番プロジェクトの Project ID と Secret key を入力します。テストする場合は、テストプロジェクトの Project ID と Secret key も入力します（「設定」を参照）。

6. Enable / Disable をオンにして保存します。Test mode をオンにしてテスト決済を行い、その後 Test mode のチェックを外すと、実際の決済を受け付けられます。

バージョン 1.0 から更新した場合、Project ID と Secret key は本番用の認証情報として保持され、テストモードはオフになります。更新後に設定を確認してください。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > TrustPay / finby。ゲートウェイが有効になっているのに、現在のモードの Project ID または Secret key が空の場合や、ストアの通貨が対応していない場合、フィールドの上に警告が表示されます。どちらの場合も、チェックアウトでは決済方法が表示されません。決済方法の一覧では、現在のモードに Project ID と Secret key が設定されるまで、ゲートウェイは設定が必要な状態として表示されます。

General

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

Title: チェックアウトで購入者に表示される決済方法の名前。デフォルト: Card payment (TrustPay)。

Description: チェックアウトで決済方法の下に表示されるテキスト。デフォルト: Pay securely by card on the TrustPay / finby payment page.

API credentials

finby（TrustPay）Merchant Portal から、プロジェクトの Project ID と Secret key をコピーします。このセクションには Merchant Portal へのリンクがあります。テスト決済では、別途テスト（playground）プロジェクトを使用します。このプロジェクトには独自の Project ID と Secret key があります。実際の料金は請求されません。

Test mode: Use the test project (no real payments)。新規の決済と返金にはテスト用の認証情報を使用します。注文の返金は、常にその注文の決済に使われたプロジェクトに対して行われます。デフォルト: オン。

Live Project ID: 本番プロジェクトの数値の Project ID。

Live Secret key: 本番プロジェクトの Secret key。API アクセストークンの取得と、決済通知の検証に使用されます。

Test Project ID: テスト（playground）プロジェクトの数値の Project ID。

Test Secret key: テストプロジェクトの Secret key。

Project ID には数字のみを含める必要があります。別の値を保存すると、ページにエラーが表示され、以前の値が保持されます。Secret key は入力したとおりに保存されます。先頭と末尾のスペースだけが削除されます。

Payment notifications

注文が支払い済みになるのは、finby が署名付きの通知で決済を確認した後だけです。プラグインは決済のたびに通知 URL を自動で送信するため、設定は不要です。このセクションには、たとえば https://your-site/wc-api/trustpay_payment_callback/ のような URL が表示されます。Merchant Portal でプロジェクトの通知 URL として入力することもできます。有効な署名がない通知は拒否されます。

プラグイン自身が finby に決済ステータスを問い合わせることはありません。通知が貴サイトに届かない場合、finby が通知を送信するまで、注文は Pending payment のままになります。

Advanced

Order status after payment: 決済成功後に設定される注文ステータス。ステータスは 1 回の操作で設定されるため、購入者に届くメールは 1 通だけです。

Debug logging: Log API requests and notifications をオンにすると、ログに詳細が追加されます。このオプションがオフでも、エラーは常に記録されます。ログは WooCommerce > Status > Logs にあり、ソースは wcp_trustpay_gateway です。キー、トークン、カード情報、購入者の詳細は含まれません。デフォルト: オフ。

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (order data is kept)。デフォルト: オフ。

チェックアウト

購入者は決済方法（デフォルトは Card payment (TrustPay)）を選んで注文します。テストモードでは、チェックアウトの説明文の下に Test mode: no real payment will be taken. と表示されます。

カード決済には請求先住所が必要です。番地、市区町村、郵便番号、国のいずれかが欠けている場合、購入者には Please enter your billing address (street, city, postcode and country) — it is required for card payments. と表示されます。

プラグインは、注文金額を注文通貨で指定したカード決済リクエストを finby に作成します。購入者の氏名、住所、メールアドレスは 3-D Secure のために送信され、注文 ID は参照番号として送信されます。購入者は finby の決済ページにリダイレクトされ、そこでカード決済を行います。finby が対応している場合は、ページはストアの言語で表示され、対応していない場合は英語で表示されます。注文のメモには、決済リクエスト、金額、プロジェクト（テストまたは本番）が表示されます。

支払い後、購入者はストアの注文受付ページに戻り、カートは空になります。注文が支払い済みになるのは、finby が署名付きの通知で確認した後だけです。戻る操作そのものが決済ステータスを変えることはありません。

購入者が決済ページでキャンセルした場合、または決済ページがエラーを返した場合、購入者は Pay for order ページに戻ります。そこには The card payment was cancelled. You can try again or choose another payment method. または The card payment was not completed. Please try again or choose another payment method. というメッセージが表示されます。注文にはメモが追加されます。購入者はそのページから再度支払うことができます。

finby が決済を開始できない場合、購入者には We could not start the card payment. Please try again in a moment or choose another payment method. と表示されます。技術的な理由はログに記録されます。

通貨: EUR、CZK、HUF、GBP、PLN、NOK、SEK、DKK、BGN、RON、CHF、USD。HUF の金額は小数点なしで送信されます。Pay for order ページでは、注文通貨が確認されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage（HPOS）に対応しています。プラグインには英語、スロバキア語、チェコ語の翻訳が含まれています。

プラグインは、finby のページでの 1 ステップの購入として、カード決済のみに対応しています。銀行振込などの他の finby 決済方法、Apple Pay や Google Pay のボタン、保存済みカード、サブスクリプションや定期決済、オーソリとキャプチャの分離、ステータスのポーリングには対応していません。

注文と返金

注文ステータス

Pending payment: 購入者は finby に送られたものの、まだ支払っていないか、通知がまだ届いていない状態です。

Processing or Completed: finby が決済を確認し、金額と通貨が決済リクエストおよび注文合計と一致している状態です。ステータスは Order status after payment の設定に従います。注文のメモには、金額、決済リクエスト、プロジェクトが表示されます。トランザクション ID は finby の決済リクエスト ID です。

On hold: 次の 3 つの場合に設定されます。決済が finby でまだ保留中で、注文が最終結果を待っている場合。決済がオーソリのみで、キャプチャされていない場合: finby Merchant Portal でキャプチャするかキャンセルしてから、注文を更新してください。または、支払われた金額や通貨が決済リクエストや注文合計と異なる場合です。たとえば、購入者が決済ページに送られた後に注文が編集された場合などです。発送前に決済を確認してください。注文のメモに詳細が記載されます。

Failed: finby が注文の最新の決済を拒否した状態です。finby が理由を送信した場合、メモに理由が表示されます。購入者は Pay for order から再度支払うことができます。

キャンセルまたは返金された注文が、遅れて届いた決済によって再開されることはありません。メモには、Merchant Portal で注文を復元するか、決済を返金するように通知が表示されます。すでに支払い済みの注文に 2 回目の決済が届いた場合、注文は変更されず、メモには Merchant Portal で重複分を返金するように表示されます。finby から報告されたチャージバックや紛争は、メモとして追加されます。

Refunds

注文を開き、Refund をクリックして金額を入力し、Refund via Card payment (TrustPay) をクリックします（ボタンには貴店の Title が表示されます）。全額返金と一部返金に対応しています。返金は、注文の決済に使われたプロジェクト（テストまたは本番）に対して行われます。その後にモードを切り替えていても同じです。そのため、そのモードの Project ID と Secret key が設定されている必要があります。HUF の返金は、整数の金額である必要があります。

返金は、finby が受け付けた場合にのみ記録されます。それ以外の場合、WooCommerce には理由とともに TrustPay refused the refund: が表示され、返金は作成されません。返金に成功すると、注文のメモに追加されます。

finby Merchant Portal で行われた返金は、WooCommerce の返金としては記録されません。それらについて finby から通知が届いた場合は、注文のメモとして追加され、注文ステータスは変わりません。

ライセンスキー

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

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

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

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

トラブルシューティング

Card payment (TrustPay) がチェックアウトに表示されない: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードに Project ID と Secret key が設定されていることを確認してください。テストモードでは Test Project ID と Test Secret key、本番モードでは Live Project ID と Live Secret key です。ストアの通貨、または Pay for order ページの注文通貨は、対応している通貨のいずれかである必要があります。設定ページには、どちらの場合も警告が表示されます。開発者は、trustpay_p_supported_currencies フィルターを使って通貨リストを変更できます。

決済は完了したのに、注文が Pending payment のまま: 通知が貴店に届いていません。https://your-site/wc-api/trustpay_payment_callback/ がインターネットからアクセスできることを確認してください（ファイアウォール、メンテナンスモード、パスワード保護がないこと）。finby は通知を再送します。WooCommerce > Status > Logs を確認してください。ソースは wcp_trustpay_gateway です。

ログに Notification rejected: invalid signature or unknown project と表示される: 通知が、Project ID が設定にないプロジェクトから届いたか、そのプロジェクトの Secret key が誤っています。店舗は Invalid signature と応答し、注文は変更されません。決済を行ったモードの Project ID と Secret key を確認してください。

ログに Notification ignored と表示される: 通知は、この店舗がその注文に対して作成していない決済リクエストに関するものか、決済を開始したものとは別のプロジェクトに関するものです。注文は変更されません。

通知に Busy, retry later と返される: 注文が、同じタイミングで別の通知によって更新されていました。finby が再送します。

購入者に We could not start the card payment と表示される: ログを開いてください。Project ID または Secret key が誤っていると、finby がプロジェクトの認証情報を拒否したというメッセージになります。テストの認証情報はテスト用のフィールドに、本番の認証情報は本番用のフィールドに入力されているか確認してください。

カード決済が一時的に利用できない: 現在のモードに Project ID または Secret key がない場合、購入者にこのメッセージが表示されます。それらを入力して保存してください。

注文が On hold で、金額/通貨の不一致のメモが表示される: 通知は正規のものでしたが、支払われた金額や通貨が決済リクエストや注文合計と一致していません。発送前に Merchant Portal で決済を確認し、その後で注文を完了するか、決済を返金してください。

返金が、プロジェクトに関するメッセージで失敗する: 注文はテストプロジェクトまたは本番プロジェクトで決済されています。そのモードの Project ID または Secret key が設定されていないか、現在別の Project ID が保存されています。そのプロジェクトの認証情報を入力するか、finby Merchant Portal で決済を返金してください。

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

アンインストール

プラグインを無効にしてもすべてのデータは保持されます。削除するには、無効にしてから、Plugins ページで削除してください。このプラグインのライセンスキーとライセンスステータス、およびキャッシュされた API アクセストークンは、常に削除されます。ゲートウェイの設定とプラグインのログ（古いローテーションファイルを含むログファイルと、データベース内のログエントリ）は、Delete data on uninstall がオンの場合にのみ削除されます。それ以外の場合は、後で再インストールするために残ります。注文データは保持されます。既存の注文は、決済のメモ、決済リクエスト ID、トランザクション ID を保持します。

TrustPay と finby は、それぞれの所有者の商標です。本プラグインは TrustPay または finby と提携しておらず、両社の承認も受けていません。