VibeFox Paytrail for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 ～ 9.x。

PHP: 8.0 以降。古いバージョンの PHP ではモジュールをインストールできません。

通貨: EUR。Paytrail はユーロのみを受け付けます。他の通貨のカートの場合、チェックアウトで決済方法は表示されません。金額はセント単位で送信されます。

ショップのインターネット接続: Paytrail はすべての決済をサーバー間コールバックで確認するため、ショップはインターネットからアクセス可能である必要があります。コールバックがなくても、購入者が Paytrail から戻った時点で注文は作成されます。

Paytrail アカウント: 加盟店 ID（Merchant ID）と秘密鍵（Secret key）が必要です。これらは Paytrail マーチャントパネル（アカウントまたは統合の詳細）に表示されます。テストには、アカウントは不要です。テストモードでは Paytrail の公開テストアカウントを使用します。決済方法自体は Paytrail アカウントで有効化します。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox Paytrail Gateway を見つけて Configure をクリックすることもできます。

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

4. まずモジュールを試すには、Test mode を有効にします。実際の支払いには、無効にしてから Merchant ID と Secret key を入力します。Paytrail でコールバック URL を設定する必要はありません。

5. Enable/Disable を有効にして Save をクリックします。

インストール時にモジュールは 2 つの注文ステータス Awaiting Paytrail payment と Paytrail payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Paytrail Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。テストモードが有効な間、フィールドの上に Test mode is active. Payments use the public Paytrail test account — no real money is charged. と表示されます。本番モードでは、Merchant ID または Secret key が未入力の場合、または Merchant ID が公開テストアカウント 375917 の場合に警告されます。ショップの通貨が EUR でない場合にも警告されます。これらの場合はいずれも、チェックアウトに Paytrail は表示されません。

保存時、数字以外の文字を含む Merchant ID は保存されず、Paytrail merchant ID must contain digits only. The previous value was kept. というエラーが表示されます。Title を空にすることはできません。

Paytrail

Enable/Disable: Enable Paytrail は決済方法のオン／オフを切り替えます。デフォルト: off。

Title: チェックアウト中に購入者に表示されるタイトル。注文に保存される決済方法名にもなります。デフォルト: Paytrail。必須。

Description: チェックアウト中、決済方法の下に購入者に表示されるテキスト。デフォルト: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

API 認証情報

加盟店 ID と Secret key は Paytrail マーチャントパネル（アカウントまたは統合の詳細）に表示されます。このセクションには、マーチャントパネルへのリンクがあります。EUR での支払いのみに対応しています。

Test mode: 新しい支払いには、お客様自身の認証情報の代わりに Paytrail の公開テストアカウント（加盟店 ID 375917）を使用します。実際の料金は請求されず、キーも不要です。購入者には決済方法の下に Test mode: no real payment will be made. と表示されます。テストアカウントの Secret key は公開されているため、誰でもテストモードでの支払いを模倣できてしまいます。本番ショップではテストモードを絶対に有効にしないでください。デフォルト: off。

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

Secret key: お客様の Paytrail Secret key。テストモードが無効のときに使用されます。保存されたキーが再表示されることはありません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved secret key: Secret key にチェックを入れて Save をクリックすると、保存済みのキーが削除されます。フィールドが空の場合は保存済みの値が保持されます。

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

注文

Callback URL: Paytrail がすべての決済をサーバー間で確認する URL を表示します。フレンドリー URL の場合、次のようになります：https://your-shop/module/wcp_paytrail_gateway/callback。決済ごとに送信されるため、Paytrail パネルで設定する必要はありませんが、ショップがインターネットからアクセス可能である必要があります。

Order status after payment: 支払い済み注文のステータス。

Processing (default): 注文には PrestaShop の標準ステータス Payment accepted が設定されます。

Completed: 支払い済みのすべての注文は Delivered になります。

保留中の支払いは Awaiting Paytrail payment で待機します。金額の不一致やその他の問題は、必ず Paytrail payment on hold になります。

詳細設定

Debug log: API リクエストとコールバックを、モジュールフォルダ内の logs/ptg_debug.log.php に記録します。このファイルは Web から開くことはできません。個人データとキーは記録されません。エラーと警告は常に記録されます。デフォルト: off。

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

Delete data on uninstall: 有効にすると、モジュールのアンインストール時に設定とログが削除されます。モジュールを無効にしても何も削除されません。注文の Paytrail トランザクションデータは、古い注文の返金に必要なため、常に保持されます。デフォルト: off。

チェックアウト

決済ステップで、購入者は決済方法（デフォルトは Paytrail）を選択して確定します。モジュールはカート合計額をユーロで指定した Paytrail 決済を作成し、注文明細を一緒に送信します。明細は、カートルール適用後の商品、送料、ギフトラッピングで、それぞれに小数点以下 1 桁までの消費税率が適用されます。明細の合計は常に決済金額と一致します。端数の差額は 1 つの明細に加算されるか、Rounding 明細として送信されます。請求先住所と配送先住所は、完全な場合にのみ送信され、長すぎる値は Paytrail の上限に合わせて短縮されます。決済ページの言語は、カートの言語に従い、フィンランド語、スウェーデン語、英語のいずれかになります。この時点ではまだ注文は存在しません。

購入者は Paytrail の決済ページに移動し、貴店の Paytrail アカウントで有効化された決済方法を選んで支払います。その後、Paytrail は支払いを 2 回確認します。購入者をショップに戻すことと、サーバー間でコールバック URL を呼び出すことです。どちらも、その決済試行の認証情報で作成された有効な署名がある場合にのみ受け付けられ、かつそのカートに対して作成された試行である場合にのみ有効です。支払金額はカート合計と比較されます。注文は、Paytrail がこの方法で確認した後にのみ支払い済みとしてマークされます。モジュールは次の Paytrail ステータスを処理します：

ok: 支払いが完了しました。金額が一致する場合、Order status after payment のステータスで注文が作成されます。

pending, delayed: 支払いは、請求書の承認などの決済プロバイダーの処理を待っています。注文は Awaiting Paytrail payment で作成され、Paytrail が確認または拒否したときに更新されます。

fail: 支払いが失敗したか、キャンセルされました。最後の試行では注文は作成されず、購入者は再度支払うことができます。確認待ちの注文は Payment error になります。支払い済みの注文は決して変更されません。

支払いが成功すると、購入者には標準の注文確認ページが表示され、Your Paytrail payment has been received. と表示されます。保留中の支払いの場合、ページには Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again. と表示されます。コールバックがまさに同じタイミングで支払いを記録している場合、Payment confirmation ページが購入者に再度支払わないよう求め、Check again ボタンを表示します。

支払いがキャンセルされた場合や失敗した場合、購入者はチェックアウトに戻り、The Paytrail payment was cancelled or failed. You can try again or choose another payment method. と表示されます。支払いがまだ完了していない場合のメッセージは The Paytrail payment has not been completed yet. You can try again or choose another payment method. です。カートは保持されます。検証できない戻りでは Payment verification failed. と表示され、何も変更されません。

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 の上限を超える合計金額の場合は This order total cannot be paid with Paytrail. Please choose another payment method. と表示されます。

Paytrail の支払いは API ではキャンセルできません。カートに対する新しい試行はそれぞれ新しい Paytrail 決済になります。購入者がまだ開いている古い決済ページからも支払った場合、2 回目の支払いは注文上で返金対象の重複として報告されます。

コールバックはショップがメンテナンスモードの間も動作し、ショップの国別制限によってブロックされることはありません。

購入者は、貴店のチェックアウトではなく、Paytrail のページで決済方法を選択します。本モジュールには、カードトークン化や保存済みカード、サブスクリプション、shop-in-shop、請求書の手動有効化、精算レポートはありません。

注文と返金

注文ステータス

注文はまだありません: 購入者は Paytrail に転送されたものの、まだ支払っていないか、Paytrail がまだ支払いを確認していません。カートのみが存在します。

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

Awaiting Paytrail payment: 支払いは決済プロバイダーで保留中です（請求書払いまたは遅延支払い）。注文は、Paytrail が支払いを確認すると支払い済みステータスに移行し、失敗した場合は Payment error に移行します。

Paytrail payment on hold: 支払い金額が注文合計と異なる（実際に支払われた金額が記録されます）、注文がキャンセルされた後に支払いが届いた、またはショップが本番モードの間にテスト支払いを受け取った（実際の金銭なし、何も記録されません）場合。メモに理由が記載されます。注文を確認した後、処理するか支払いを返金してください。

Payment error: 保留中の支払いが失敗またはキャンセルされました。

Refunded: モジュールを通じて支払いが全額返金されました。

繰り返しまたは並行して届くコールバックによって、2 つ目の注文やメモの重複が作成されることはありません。すでに支払い済みのカートに対する 2 回目の試行が支払われた場合、注文は変更されません。Duplicate payment のメモは、Paytrail マーチャントパネルで返金するよう求めます。

Paytrail 支払いブロック

注文ページには Paytrail payment ブロックが表示され、トランザクション ID、モード（テスト支払いには TEST mode バッジ）、決済方法、Paytrail ステータス、支払額と返金額、返金フォーム、返金履歴、カートの支払い試行、注文の Paytrail notes が含まれます。

返金

Paytrail payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて注文メモ用の理由を入力し、Refund via Paytrail をクリックします。Refund this amount through Paytrail? This cannot be undone. の確認に同意してください。全額返金と一部返金に対応しており、金額単位のみです。注文を編集する権限が必要です。モジュールのページへのアクセス権は不要です。Paytrail が実際に受け取った金額まで返金できるため、金額の不一致後は、上限は注文合計ではなく購入者が支払った金額になります。返金は、支払いが行われたモードの認証情報を使用するため、本番の支払いには本番の認証情報を設定しておく必要があります。返金は、Paytrail が支払いを確認した後に利用できます。

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

返金は即座に完了することも、後で処理されることもあります。Paytrail の後からの確認はメモとして追加されます。Paytrail が返金を完了できなかった場合は、お金が購入者に返金されていないことがメモに記載され、その返金は返金済みとはみなされなくなります。別の方法で購入者に返金してください。Paytrail が返金をすぐに拒否した場合、ブロックにエラーが表示され、返金は記録されません。全額返金の場合は注文が Refunded に設定されます。一部返金ではステータスは変わりません。

モジュールはクレジットスリップを作成しません。注文ページ上の標準 PrestaShop の返金ボタンでは、Paytrail を通じて返金は行われません。Paytrail マーチャントパネルで行われた返金は、PrestaShop に同期されません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Paytrail が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、そして Test mode がオンであるか、Merchant ID と Secret key が入力されていること（公開テストアカウント 375917 ではないこと）を確認してください。カートの通貨が EUR であることを確認します。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループに対して許可されているかを確認してください。設定ページには、認証情報の未入力やショップ通貨の誤りに関する警告が表示されます。

決済は完了したが注文が作成されない: コールバックがショップに届かず、購入者もショップに戻っていません。注文セクションに表示される Callback URL は、インターネットからアクセス可能である必要があります（基本認証やファイアウォールで阻止されていないこと）。

コールバックまたは戻りで Payment verification failed. と表示される: 署名が無効であるか、その決済がカートの決済試行に属していません。何も変更されません。Secret key が正しく、Merchant ID に対応していることを確認してください。

コールバックが Temporarily unavailable と応答する: 注文がほぼ同時に別のリクエストによって確認されていたか、注文を作成できませんでした（例：モジュールが無効）。Paytrail は再度呼び出します。理由は Log フィールドを確認してください。

購入者が Paytrail を選択するとエラーが表示される: モジュールページの Log フィールドを確認してください。例えば Paytrail API error (401) は認証情報の誤りを意味します。詳細は Debug log を有効にしてください。

Merchant ID が保存されない: 数字のみでなければなりません。Paytrail マーチャントパネルから再度コピーしてください。

注文が Paytrail payment on hold になっている: Paytrail payment ブロックのメモを確認してください。理由は、異なる支払額、キャンセル後の支払い、または本番モードでのテスト支払いです。

返金が失敗する: メッセージを確認してください。This order has no confirmed Paytrail payment. Refund it manually. は、返金すべき確認済みの Paytrail 支払いがないことを意味します。The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. は、支払いが本番モードで行われたが本番の認証情報が設定されていないことを意味します。Invalid refund amount: at most … は、金額が返金可能な残高を超えていることを意味します。決済方法がメールによる返金のみに対応している場合、注文には購入者のメールアドレスが必要です。

開発者向けフック: actionWcpPaytrailPaymentRequest フックは、支払いリクエストが署名されて送信される前に、そのリクエストを変更します。

アンインストール

Modules > Module Manager に移動し、VibeFox Paytrail Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall が有効な場合、設定とログが削除されます。無効な場合は、後で再インストールするためにすべての設定が保持されます。Paytrail のトランザクションと返金、および注文ステータス Awaiting Paytrail payment と Paytrail payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いメモとトランザクション ID を保持します。

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