VibeFox TrustPay for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールを拒否します。

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

到達可能な通知 URL: finby からショップにインターネット経由でアクセスできる必要があります。ショップの前にあるファイアウォール、メンテナンス用ログイン、または HTTP 認証があると、決済通知がブロックされます。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後で探す場合は、モジュール一覧から VibeFox TrustPay Gateway を見つけて Configure をクリックします。

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

4. テストプロジェクトの Project ID と Secret key を入力します。実際の決済を行う場合は、本番プロジェクトの Project ID と Secret key も入力します（設定の項を参照）。

5. Enable / Disable をオンにして Save をクリックします。Test mode をオンにした状態でテスト決済を行い、その後 Test mode をオフにすると、実際の決済を受け付けられます。

インストール時に、モジュールは 2 つの注文ステータス Awaiting TrustPay payment と TrustPay payment on hold を作成します。PrestaShop は、新しい決済モジュールをインストール時に有効だった国に関連付けます。後から追加する国については、Payment > Preferences でモジュールにチェックを入れてください。そこでは、通貨や顧客グループによってモジュールを制限することもできます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox TrustPay Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、モジュールが有効なのに現在のモードの Project ID または Secret key が空の場合や、ショップの既定通貨がサポートされていない場合に警告が表示されます。どちらの場合も、決済方法はチェックアウトで非表示になります。

TrustPay / finby

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

Title: 購入者がチェックアウトで見る決済方法の名前です。注文に保存される決済方法の名前でもあります。既定値：Card payment (TrustPay)。必須。

Description: チェックアウトで決済方法の下に表示される文章です。既定値：Pay securely by card on the TrustPay / finby payment page.

API の認証情報

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

Test mode: テストプロジェクトを使用します（実際の決済は行われません）。新しい決済と返金にはテストの認証情報が使われます。注文の返金は、常にその注文の決済に使われたプロジェクトに対して行われます。既定値：on。オンの間、購入者には決済方法の下に Test mode: no real payment will be taken. と表示されます。

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

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

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

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

Project ID には数字だけを入力する必要があります。別の値を保存すると、ページに must contain digits only — the previous value was kept. と表示されますが、他のフィールドは保存されます。Secret key は入力したとおりに保存され、先頭と末尾の空白のみが削除されます。保存済みの Secret key が再度表示されることはありません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。設定を保存すると、キャッシュされた API アクセストークンも破棄されるため、新しい認証情報がすぐに使用されます。

Clear saved secrets: Secret key にチェックを入れ、Save をクリックすると削除されます。空のフィールドは、保存されている値を保持します。

決済通知

注文は、finby が署名付きの通知で確認した後にのみ支払い済みになります。モジュールは、すべての決済に通知 URL を自動的に送信するため、設定は不要です。このセクションでは、Notification URL の下に URL が表示されます。フレンドリー URL を使用している場合、https://your-shop/module/wcp_trustpay_gateway/callback のような形式になり、言語コードが付くこともあります。Merchant Portal で、プロジェクトの通知 URL としてこれを入力することもできます。有効な署名のない通知は拒否されます。

モジュールは、自分から finby に決済ステータスを問い合わせることはありません。通知がショップに届かない場合、finby が再送するまで注文は作成されません。finby は通知を再試行します。

詳細設定

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

Debug logging: API リクエストと通知を、モジュールフォルダ内の logs/trustpay_p_debug.log.php に追記します。このファイルは Web から開くことができません。このオプションがオフでも、エラーは常に記録されます。ログにはキー、トークン、カードデータ、購入者の詳細は含まれません。既定値：off。

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

Delete data on uninstall: オンにすると、モジュールのアンインストール時にモジュールの設定とログが削除されます。注文データは保持されます：注文、TrustPay の決済記録と返金、および注文ステータスです。既定値：off。

チェックアウト

支払いの段階で、購入者は決済方法（既定では Card payment (TrustPay)）を選択し、注文を確定します。決済方法は、対応している通貨でのみ提供されます：EUR、CZK、HUF、GBP、PLN、NOK、SEK、DKK、BGN、RON、CHF、USD。HUF の金額は小数点なしで送信されます。

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

モジュールは、カートの通貨でカート金額のカード決済リクエストを finby に作成します。購入者の氏名、住所、メールアドレスは 3-D Secure のために送信され、カート番号は参照用として送信されます。この時点では、まだ注文は存在しません。購入者は finby の決済ページにリダイレクトされ、そこでカード決済を行います。finby が対応している場合、ページはカートの言語で表示され、対応していない場合は英語で表示されます。

決済後、購入者はショップに戻ります。注文は、finby が署名付きの通知で確認した後にのみ支払い済みになります。戻ってくるという行為そのものが、決済ステータスを変更することはありません。通知がすでに届いている場合、購入者には通常の注文確認ページが表示されます。まだ届いていない場合は、Payment confirmation ページが表示され、finby がカード決済を確認中であり、確認が取れ次第注文が作成されることが示されます。このページには Check again ボタンと Back to checkout ボタンがあります。注文が Awaiting TrustPay payment または TrustPay payment on hold の間、確認ページには Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. と表示されます。finby が決済を拒否した場合、または未払いの注文がキャンセルされた場合は、Your card payment was not completed. Please contact us about this order. と表示されます。

購入者が決済ページでキャンセルした場合、チェックアウトに戻り、The card payment was cancelled. You can try again or choose another payment method. と表示されます。決済ページがエラーを返した場合、または finby がすでに決済を拒否していた場合、メッセージは 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. と表示されます。技術的な理由はログに書き込まれます。

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

モジュールはカード決済のみを扱い、finby のページで 1 回の操作で完了する購入として処理されます。銀行振込や finby のその他の決済方法、ショップ上の Apple Pay や Google Pay のボタン、保存済みカード、サブスクリプションや定期払い、オーソリとキャプチャの分離、ステータスのポーリングには対応していません。

注文と返金

注文ステータス

No order yet: 購入者は finby に移動したものの、まだ支払っていないか、通知がまだ届いていません。存在するのはカートだけです。

Payment accepted or Delivered: finby が決済を確認し、金額と通貨が決済リクエストおよびカート合計と一致しています。ステータスは Order status after payment に従います。決済は、finby の決済リクエスト ID をトランザクション ID として記録され、メモには金額、決済リクエスト、プロジェクト（テストまたは本番）が表示されます。

Awaiting TrustPay payment: finby が最新の決済を保留中と報告しています。finby が決済を確認すると、注文は支払い済みのステータスに移ります。

TrustPay payment on hold: 2 つの場合に設定されます。決済が承認のみで、キャプチャされていない場合です。finby Merchant Portal でキャプチャまたはキャンセルし、その後注文を更新してください。または、支払われた金額または通貨が決済リクエストまたはカート合計と異なる場合です（たとえば、購入者が決済ページに送られた後にカートが変更された場合）。出荷前に決済を確認してください。メモにその内容が説明されています。

Payment error: 保留中だった注文について、finby が最新の決済を拒否しました。finby が理由を送信している場合、メモにその理由が表示されます。その後に確認された決済があれば、注文は支払い済みのステータスに移ります。

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

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

TrustPay / finby 決済ブロック

注文ページには TrustPay / finby payment ブロックが表示されます。このブロックには、決済リクエスト ID、finby の決済 ID、プロジェクト、決済ステータス、請求額と支払い額、返金済みの金額、テスト決済用の Test project バッジ、返金履歴、そして注文の TrustPay notes が含まれます。

返金

TrustPay / finby payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via TrustPay をクリックします。Refund this amount through TrustPay? This cannot be undone. の確認に応答してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。モジュールのページへのアクセス権は必要ありません。返金は、finby が決済について報告した金額と通貨で行われます。そのため、金額の不一致があった場合は、注文合計ではなく、購入者が実際に支払った金額まで返金できます。HUF の返金は整数である必要があります。

返金は、その後モードを切り替えていても、注文の決済に使われたプロジェクト（テストまたは本番）に対して行われます。そのプロジェクトの Project ID と Secret key が設定されている必要があり、その Project ID が変更されていてはなりません。返金は、finby が受け付けた場合にのみ記録されます。受け付けられなかった場合、ブロックには理由とともに TrustPay refused the refund: が表示され、返金は記録されません。返金が成功すると、返金履歴とメモに追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。

モジュールはクレジットスリップを作成しません。注文ページにある PrestaShop の標準の返金ボタンでは、finby を通じて返金されることはありません。finby Merchant Portal で行われた返金は、返金として記録されません。それらについて finby から通知が届いた場合は、メモとして追加され、注文ステータスは変わりません。

ライセンスキー

モジュールは、vibefox.net で発行された VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox TrustPay Gateway は、Modules > Module Manager > VibeFox TrustPay Gateway > Configure ページの最初のブロックで、設定の上に表示されます。キーを License key に入力して Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（例：ライセンスの有効期限日とお使いのドメイン）と、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-payment-trustpay の行と、vibefox.net のアカウントを開く Manage licenses and domains in your account のリンクがあります。キーを変更できるのは、このモジュールの Configure 権限を持つ従業員のみです。ブロックのテキストはバックオフィスの言語に従います（英語とロシア語を含みます）。

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

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

有効なキーがない場合、チェックアウトでカード決済は購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントはバックオフィスにログインしていることを認識しないため、ログイン中の管理者にも決済方法は表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された決済は、TrustPay の通知とショップへの復帰によって引き続き確認され、返金も利用できます。

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

トラブルシューティング

Card payment (TrustPay) がチェックアウトに表示されない: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードに Project ID と Secret key が設定されていることを確認してください。テストモードでは Test Project ID と Test Secret key、本番モードでは Live Project ID と Live Secret key です。カートの通貨は、対応している通貨のいずれかである必要があります。設定ページには、認証情報がない場合や既定通貨がサポートされていない場合に警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループについて許可されているか確認してください。

決済は完了したが、注文が作成されなかった: 通知がショップに届かなかった可能性があります。Notification URL の下に表示される URL がインターネットから到達可能か（ファイアウォール、メンテナンス用ログイン、HTTP 認証がないか）確認してください。finby は通知を再試行し、通知が届いた時点で注文が作成されます。Debug logging をオンにして、モジュールのページの Log フィールドを確認してください。

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

ログに Notification ignored が表示される: 通知は、このショップがそのカートについて作成していない決済リクエストに関するものか、決済の開始時とは異なるプロジェクトまたはモードに関するものです。何も変更されません。

通知に Busy, retry later または Temporary error が返される: 同じ時点で、別の通知によってカートが更新されていたか、注文を作成できませんでした（たとえば、モジュールが無効になっている場合）。finby は再試行します。ログに理由が表示されます。

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

Card payment is temporarily unavailable: 現在のモードに Project ID または Secret key がない場合、購入者にこのメッセージが表示されます。それらを入力して保存してください。

注文が TrustPay payment on hold になっている: TrustPay / finby payment ブロックのメモを確認してください（注文ステータスの項を参照）。出荷前に Merchant Portal で決済を確認し、その後、注文を完了させるか、決済を返金してください。

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

Invalid refund amount: at most … can be refunded: 金額が、支払い額からモジュールを通じてすでに行われた返金を差し引いた額を超えています。

アンインストール

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

TrustPay と finby は、それぞれの所有者の商標です。このモジュールは TrustPay または finby と提携しておらず、両社による推奨も受けていません。