VibeFox Paytrail for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

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

PHP: 8.0 以降。

ストア通貨: EUR。Paytrail はユーロのみを受け付けます。その他の通貨では、チェックアウト時に決済方法が非表示になります。金額はセント単位で送信されます。

サイトへのインターネットアクセス: Paytrail はサーバー間コールバックで各決済を確認するため、サイトがインターネットからアクセス可能である必要があります。コールバックがない場合でも、購入者が Paytrail から戻った時点で注文は確認されます。

Paytrail アカウント: Paytrail Merchant Panel（アカウントまたは統合の詳細）に表示される Merchant ID と Secret key が必要です。テスト用にはアカウントは不要です。テストモードでは Paytrail の公開テストアカウントが使用されます。決済方法自体は、貴店の Paytrail アカウント内で有効化します。

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

インストール

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

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

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

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

5. プラグインをまず試す場合は、Test mode にチェックを入れます。本番の決済を行う場合はチェックを外し、Merchant ID と Secret key を入力します。Paytrail 側でコールバック URL を設定する必要はありません。

6. Enable/Disable を有効にして保存します。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Paytrail。テストモードが有効な間、フィールドの上部に Test mode is active. と表示されます。本番モードでは、Merchant ID または Secret key が不足している場合、およびストア通貨が EUR でない場合に警告が表示されます。どちらの場合も、チェックアウト時に Paytrail は表示されません。決済方法一覧では、本番モードで認証情報が設定されていない間、Paytrail は設定が必要と表示されます。

保存時に、数字以外の文字が含まれる Merchant ID は保存されません。エラーが表示され、以前の値が保持されます。

General

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

Title: チェックアウト時に購入者に表示されるタイトル。既定値: Paytrail。

Description: チェックアウト時に購入者に表示される説明文。既定値: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

API credentials

Merchant ID と Secret key は Paytrail Merchant Panel（アカウントまたは統合の詳細）に表示されます。EUR 決済のみ対応しています。

Test mode: Use the Paytrail test account。新規決済には、貴店独自の情報ではなく Paytrail の公開テストアカウント（Merchant ID 375917）が使用されます。実際のお金が請求されることはありません。購入者にはチェックアウト時に Test mode: no real payment will be made. と表示されます。テストアカウントの Secret key は公開されているため、テストモードで作成された注文に対して誰でも決済をシミュレートできてしまいます。本番のショップでテストモードを有効にしたままにしないでください。既定値: 無効。

Merchant ID: 貴店の Paytrail 加盟店 ID（数字のみ）。テストモードが無効のときに使用されます。

Secret key: 貴店の Paytrail 秘密キー。テストモードが無効のときに使用されます。

コールバックと返金は常に決済が行われたモードの認証情報を使用するため、テストと本番を切り替えても古い注文に影響はありません。

Orders

このセクションには、https://your-site/wc-api/ptg_paytrail/ のようなコールバック URL が表示されます。Paytrail はこの URL へのサーバー間通信で各決済を確認します。この URL は決済ごとに送信されるため、Paytrail パネル側での設定は不要ですが、サイトがインターネットからアクセス可能である必要があります。

Order status after payment: 支払い済み注文のステータス。ステータスは 1 段階で設定されるため、購入者に送信されるメールは 1 通のみです。

Advanced

Debug log: Log API requests and callbacks。個人データやキーを含めずに WooCommerce > Status > Logs（ソース: wcp_paytrail_gateway）に記録されます。エラーは常にログに記録されます。既定値: 無効。

Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted。プラグインを無効化してもデータが削除されることはありません。Paytrail の取引データがないと、古い注文の返金を WooCommerce から実行できなくなります。既定値: 無効。

チェックアウト

購入者は決済方法（既定では Paytrail）を選択し、注文を確定します。プラグインは注文合計金額（ユーロ）で Paytrail 決済を作成し、注文明細（商品、送料、手数料、それぞれ小数点以下 1 桁の消費税率付き）を一緒に送信します。明細行の合計は常に決済金額と一致し、端数の誤差は明細行に組み込まれるか、Rounding 行として送信されます。請求先住所および配送先住所は完全に入力されている場合にのみ送信され、長すぎる値は Paytrail の制限に合わせて短縮されます。決済ページの言語は、ストアのロケールに従ってフィンランド語、スウェーデン語、または英語になります。

購入者は Paytrail 決済ページにリダイレクトされ、貴店の Paytrail アカウントで有効化されている決済方法を選択して支払います。その後、Paytrail は 2 回決済を確認します。購入者をストアに戻す処理と、コールバック URL をサーバー間で呼び出す処理です。どちらも、該当する決済試行の認証情報で作成された有効な署名があり、かつその注文用に作成された試行に対してのみ受け付けられます。支払われた金額は注文合計と比較されます。注文は、Paytrail がこの方法で確認した後にのみ支払い済みとしてマークされます。プラグインは以下の Paytrail ステータスを処理します:

支払いが成功すると、購入者には注文完了ページが表示されます。キャンセルまたは失敗した場合、購入者は The Paytrail payment was cancelled or failed. You can try again or choose another payment method. というメッセージとともに Pay for order ページに移動します。支払いがまだ完了していない場合、メッセージは The Paytrail payment has not been completed yet. You can try again or choose another payment method. になります。

Paytrail が支払いを開始できない場合、購入者には Could not connect to Paytrail. Please try again in a moment.、Paytrail is temporarily unavailable. Please choose another payment method.（誤った認証情報）、または Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. などの短いメッセージが表示されます。技術的な理由は注文メモとログに追加されます。Paytrail の上限金額を超える注文は、Paytrail で支払うことはできません。

Paytrail の支払いを API 経由でキャンセルすることはできません。購入者が新しい支払いを開始した後に、開いたままになっていた古い支払いページでも支払いを完了した場合、2 回目の支払いは返金対象の重複として注文メモに報告されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce 高パフォーマンス注文ストレージ（HPOS）と互換性があります。

購入者は、自店のチェックアウト画面ではなく Paytrail のページで決済方法を選択します。このプラグインには、カードのトークン化や保存、WooCommerce Subscriptions、shop-in-shop、手動の請求書有効化、精算レポートの機能はありません。

注文と返金

注文ステータス

Pending payment: Paytrail 決済が作成され、購入者はまだ支払っていません。注文メモには Paytrail トランザクション ID、金額、モードが表示されます。

Processing or Completed: 支払いが確認されました。ステータスは Order status after payment に従います。注文メモには、トランザクション、Paytrail で使用された決済方法、金額が表示されます。トランザクション ID は Paytrail のトランザクション ID です。

On hold: プロバイダー側で支払いが保留中（請求書または遅延支払い）、支払金額が注文合計と異なる、注文キャンセル後に支払いが届いた、またはショップが本番中にテスト支払いを受信した（実際のお金ではない）状態です。注文メモに理由が記載されます。注文を確認し、処理を続行するか返金を行ってください。

Failed: 最新の支払い試行が失敗したか、購入者によってキャンセルされました。購入者は再度支払うことができます。

コールバックが重複または並行して届いても、注文メモ、在庫減算、メールが重複することはありません。支払い済みの注文に対して 2 回目の試行が支払われた場合、注文が再度変更されることはなく、Duplicate payment のメモが表示され、Paytrail Merchant Panel で返金するよう求められます。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Paytrail をクリックします（ボタンには設定した Title が表示されます）。全額返金および一部返金に対応しており、金額のみの返金となります（返金商品の明細行はありません）。このボタンは、Paytrail の支払いが確認されている注文でのみ利用できます。返金には支払時と同じモードの認証情報が使用されるため、本番の支払いには本番の認証情報が設定されている必要があります。

決済方法が直接返金に対応していない場合、プラグインは自動的にメール返金を開始します。Paytrail から購入者に銀行口座を入力するためのメールが送信されます。これには注文に請求先メールアドレスが必要です。注文メモには、どの種類の返金が開始されたかが記録されます。

返金は即時に完了する場合と、後から処理される場合があります。Paytrail による事後確認はメモとして追加されます。Paytrail が返金を完了できなかった場合、購入者にお金が返金されなかったことを示すメモが記録されます。別の方法で返金を行い、WooCommerce 上の返金を削除してください。Paytrail が返金を即座に拒否した場合、WooCommerce にエラーが表示され、返金は記録されません。

Paytrail Merchant Panel で行われた返金は、WooCommerce に同期されません。

ライセンスキー

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

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

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

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

トラブルシューティング

チェックアウト時に Paytrail が表示されない: ライセンスが有効であること、Enable/Disable が有効であること、および Test mode が有効であるか Merchant ID と Secret key が入力されていることを確認してください。ストア通貨（または Pay for order ページでの注文通貨）が EUR であることを確認してください。設定ページには、これらの各問題について警告が表示されます。

支払いは完了したが、注文が Pending payment のままになる: コールバックがサイトに到達できず、購入者がストアに戻りませんでした。Orders セクションに表示されているコールバック URL がインターネットからアクセス可能である必要があります（メンテナンスモード、基本認証、途中のファイアウォールによる遮断がないこと）。

コールバックまたは復帰時に Payment verification failed. と応答する: 署名が無効であるか、その注文の支払い試行に属していない支払いであることを示します。注文は変更されません。Secret key が正しく、Merchant ID に属していることを確認してください。

決済が作成されない: 認証情報が正しくない場合など、注文メモとログに Paytrail API error (401): … などの Paytrail エラーが表示されます。Debug log を有効にし、WooCommerce > Status > Logs（ソース: wcp_paytrail_gateway）を確認してください。

Merchant ID が保存されない: 数字のみを含める必要があります。Paytrail Merchant Panel から再度コピーしてください。

注文が On hold になる: 注文メモをお読みください。原因としては、保留中または遅延支払い、支払金額の不一致、キャンセル後の支払い、または本番モードでのテスト支払いの受信が考えられます。

返金に失敗する: メッセージをお読みください。This order has no confirmed Paytrail payment. Refund it manually. は、返金対象となる確認済みの Paytrail 支払いがないことを意味します。本番認証情報の不足に関するメッセージは、支払いが本番モードで行われ、本番認証情報が設定されていないことを意味します。決済方法がメール返金のみに対応している場合、注文に請求先メールアドレスが必要です。

開発者向けフック: ptg_payment_request フィルターは、支払いリクエストが署名されて送信される前に変更します。ptg_icon フィルターはチェックアウトアイコンを変更します。

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

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイ設定、このプラグインのログ、および注文に保存されている Paytrail データ（決済試行、取引データ、返金記録）は、Delete data on uninstall が有効になっていた場合にのみ削除されます。それ以外の場合は、将来の再インストールに備えて保持されます。既存の注文は支払いメモとトランザクション ID を保持しますが、Paytrail データがないと古い注文を WooCommerce から返金できなくなります。

Paytrail は、それぞれの所有者の商標です。このプラグインは Paytrail と提携しておらず、Paytrail による推奨も受けていません。