VibeFox PagSeguro for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

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

通貨：ブラジル・レアル（BRL）。支払い方法は BRL のカートでのみ表示されます。

HTTPS：PagBank が支払い通知を送信できるように、ストアはインターネットから HTTPS でアクセス可能である必要があります。

PagBank アカウント：実際の支払い用の本番トークンと、テスト用のサンドボックストークン。本番：PagBank アカウントにログインし、Venda online > Integrações を開いて Gerar token をクリックします。PagBank からメールでトークンが届きます。サンドボックス：PagBank の開発者ポータルでサンドボックスアカウントを作成し、そのトークンをコピーします。サンドボックスと本番のトークンは、それぞれの環境でのみ有効です。

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

インストール

1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

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

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

4. サンドボックストークンを入力します。実際の支払いを受け付けるには、本番トークンも入力します。

5. Enable / Disable をオンにして Save をクリックします。Sandbox Mode をオンにした状態でテスト決済を行い、その後オフにして実際の支払いを受け付けます。

インストール時に、モジュールは 2 つの注文ステータス Awaiting PagBank payment と PagBank payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。Payment > Preferences で制限できます。ただし、BRL 通貨はモジュールで許可されたままにしておく必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox PagSeguro Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上には現在のモードが表示されます：SANDBOX MODE（支払いは PagBank のサンドボックスで作成され、実際の請求は発生しません）または LIVE（支払いは本番トークンで作成されます）。現在のモードのトークンがない場合は警告が表示されます（その場合、支払い方法はチェックアウトで非表示になります）。ストアの既定通貨が BRL でない場合も警告が表示されます（その場合、他の通貨のカートには支払い方法が提供されません）。

PagSeguro / PagBank

Enable / Disable：Enable PagSeguro/PagBank payments で支払い方法をオンまたはオフにします。デフォルト：オフ。

Title：チェックアウトで顧客に表示される支払い方法の名前です。注文にも支払い方法名として保存されます。デフォルト：PagSeguro / PagBank。必須。

Description：チェックアウトで支払い方法の下に表示されるテキストです。デフォルト：Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

PagBank アカウント

このセクションでは、トークンの取得方法を説明し、お使いの PagBank アカウントと、トークンに関する PagBank のページへのリンクを表示します。

Sandbox Mode：Enable sandbox/test mode (no real charges)。新しい支払いはサンドボックストークンを使って PagBank のサンドボックスに送信され、顧客には支払い方法の下に SANDBOX MODE — Using test environment. No real charges. が表示されます。注文のステータス確認と返金は、その支払いを作成したときの環境とトークンを常に使用します。デフォルト：オン。

Sandbox token：PagBank のサンドボックストークンです。サンドボックスモードがオンの間に使用されます。

Production token：PagBank の本番トークン（Bearer）です。サンドボックスモードがオフの間に使用されます。秘密にしてください。

保存されたトークンは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved tokens：トークンにチェックを入れて Save をクリックすると削除されます。フィールドを空のままにすると、保存されている値は保持されます。

支払い通知

Notification URL：支払いごとに、ステータスの変更を PagBank がどこに通知するかが伝えられるため、PagBank 側で設定するものはありません。このセクションには URL が表示されます。フレンドリー URL の場合は次のような形式になります：https://your-shop/module/wcp_pagseguro_gateway/webhook。このアドレスは、インターネットから HTTPS でアクセスできる必要があります。

x-authenticity-token ヘッダーを含む通知は、支払いが作成された環境のトークンで検証されます。署名が無効な通知は拒否されます。通知の本文自体は信頼されません。モジュールは、注文を作成または変更する前に、必ず PagBank API からチェックアウトと PagBank の注文（ステータス、金額、通貨）を読み取ります。通知がない場合は、購入者が支払い後にストアへ戻ったときに注文が作成されます。

詳細設定

Debug log：Log API requests and notifications をオンにすると、モジュールフォルダー内の logs/wc_psg_debug.log.php に詳細が書き込まれます。このファイルは Web から開くことはできません。ログにはトークンや顧客データは含まれません。エラーは常に記録されます。デフォルト：オフ。

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

Delete Data on Uninstall：オンにすると、モジュールをアンインストールしたときにゲートウェイの設定とログが削除されます。注文、PagBank の参照情報（返金に必要）、注文ステータスは常に保持されます。デフォルト：オフ。

チェックアウト

支払いの段階で、顧客は支払い方法（デフォルトは PagSeguro / PagBank）を選んで確定します。モジュールは、カートの合計金額を BRL で 1 つの商品として、Order # にカート番号とストア名を添えた PagBank 決済を作成し、顧客を PagBank の決済ページへ移動させます。顧客の氏名とメールアドレス、住所の Identification number または VAT number フィールドにある CPF または CNPJ、およびブラジルの電話番号は、ストアに情報がある場合に入力されます。顧客は PagBank のページで補完または修正できます。顧客は、PagBank アカウントで有効になっている支払い方法（例：クレジットカード、PIX、boleto）で支払います。決済ページは 120 分後に期限切れになります。この時点ではまだ注文は存在しません。

支払い後、顧客はストアに戻ります。注文は、PagBank が確認した後にのみ支払い済みとしてマークされます。通知が届いたとき、または顧客が戻ったときに、モジュールは API から支払いを読み取ります。戻っただけでは注文が支払い済みになることはありません。その後注文が作成され、顧客には注文確認ページに Your payment with PagBank has been received. と表示されます。発行された boleto または PIX、または審査中の支払いの場合、ページには Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. と表示されます。その支払いが後に拒否またはキャンセルされた場合、ページには Your PagBank payment was not completed. Please contact us about this order. と表示されます。顧客が戻った時点で PagBank がまだ支払いを確認していない場合は、Payment confirmation ページに We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. と表示され、Check again ボタンが付きます。

支払いが完了しなかった場合、顧客はチェックアウトに戻り、The PagBank payment was not completed. You can pay the order again below.、The PagBank payment page has expired. You can pay the order again below.、または The payment was declined by PagBank. Please try again with another card or payment method. と表示されます。カートは保持されます。boleto または PIX の支払いを待っていた注文がキャンセルされた場合、顧客には The PagBank payment was cancelled, so the order was cancelled. と表示されます。

顧客が再度支払う場合、金額と環境が同じで、10 分以内に期限切れにならなければ、未完了の PagBank 決済が再利用されます。そうでない場合は、以前の決済が無効になり、もう支払えなくなります。それより前のページで行われた支払いは引き続きカートに対して有効で、新たに支払いを作成するのではなく注文が作成されます。

PagBank が支払いを開始できない場合、顧客はチェックアウトに留まり、簡単なメッセージが表示されます。例：PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. または Could not connect to PagBank. Please try again in a moment. 技術的な理由はログに記録されます。

ストアがメンテナンスモードであっても通知は機能し、ストアの国による制限ではブロックされません。

本モジュールには、ストア内のカード入力フォーム、カードの保存、サブスクリプションや定期決済、分割決済やマーケットプレイスはありません。支払い方法と分割払いは、PagBank アカウントで設定したものが使われます。

注文と返金

注文ステータス

まだ注文なし：顧客は PagBank に移動しましたが、まだ支払っていない、カードが拒否された、または決済ページが期限切れになりました。カートのみが存在し、顧客は再度支払うことができます。

Payment accepted：支払いが想定どおりの金額と通貨で確認されました。支払いは PagBank のチャージ ID（charge ID）をトランザクション ID として記録され、メモに金額、支払い方法、チャージ ID が表示されます。

Awaiting PagBank payment：boleto または PIX が発行されて支払いを待っている、または支払いが審査中です。PagBank が支払い済みと報告すると、注文は Payment accepted に移ります。

PagBank payment on hold：PagBank がカートと異なる金額または通貨を報告した（例：決済ページの作成後にカートが変更された）、注文がキャンセルされた後に支払いが届いた（在庫を確認し、そのうえで注文を完了するか PagBank で支払いを返金してください）、またはカード支払いが承認されたもののキャプチャされていない（PagBank でキャプチャしてください）。メモにその理由が説明されます。実際に受け取った金額は注文に記録されます。

Payment error：待機中または審査中だった支払いが拒否されました。

Canceled：期限切れの boleto や PIX など、待機中だった支払いがキャンセルされました。

Refunded：支払いが、モジュール経由または PagBank のダッシュボードで全額返金されました。

各 PagBank ステータスは 1 回だけ適用されるため、通知や戻りが繰り返されてもメモやステータスの変更は追加されません。すでに支払い済みの注文に 2 つ目の支払いが届いた場合、注文は変更されず、メモで重複分を PagBank で返金するよう案内されます。

PagBank payment ブロック

注文ページには、PagBank のチェックアウト、PagBank の注文およびチャージの ID、支払い方法、ステータス、支払い済み金額と返金済み金額、サンドボックス支払い用の Sandbox バッジ、返金履歴、注文の PagBank notes を含む PagBank payment ブロックが表示されます。

返金

PagBank payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via PagBank をクリックします。確認メッセージ Refund this amount through PagBank? This cannot be undone. に同意してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。モジュールのページへのアクセスは不要です。上限は PagBank が請求した金額です。そのため金額の不一致があった後は、注文合計ではなく、顧客が実際に支払った金額まで返金できます。返金は、支払いが行われたときの環境とトークンで送信されます。返金は PagBank が確認した場合にのみ記録されます。確認されない場合、ブロックにはエラーが表示されます。例：PagBank refund failed: ... または PagBank did not confirm the refund。その場合、何も記録されません。boleto 支払いの返金や PIX の一部返金は、PagBank のルールに従います。返金が成功すると、チャージ ID とともに返金履歴とメモに追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。返金は、PagBank が支払い済みと報告した後に利用できます。

本モジュールは貸方伝票を作成しません。注文ページの PrestaShop 標準の返金ボタンでは、PagBank を通じて返金は行われません。

PagBank のダッシュボードで行った返金は、次の通知で検出されます。全額返金は注文を Refunded にし、一部返金は返金額を示すメモを追加します。返金は注文に手動で追加できます。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに PagBank が表示されない：ライセンスが有効であること、Enable / Disable がオンであること、現在のモードのトークンが設定されていること（サンドボックスモードでは Sandbox token、ライブモードでは Production token）、カートの通貨が BRL であることを確認してください。トークンが見つからない場合やストアの通貨が BRL でない場合、設定ページに警告が表示されます。Payment > Preferences で、モジュールが BRL、顧客の国、顧客のグループに対して許可されていることを確認してください。

支払いは完了したが注文が作成されない：PagBank がまだ支払いを報告しておらず、顧客がストアに戻っていません。通知が届いた時点で注文が作成されます。ストアが Notification URL で HTTPS によりインターネットからアクセスできるか確認し、Debug log をオンにして通知を確認してください。

通知の応答が Invalid signature：x-authenticity-token が、支払いが行われた環境のトークンと一致しないか、そのトークンが保存されていません。設定に正しいトークンが入力されているか確認してください。

通知の応答が Verification failed, retry later：PagBank API に接続できない、支払い環境のトークンがない、またはカートが同時に別のリクエストで処理されていました。PagBank は通知を再試行します。

通知の応答が Order not found：通知は、このストアで本モジュールを使って支払われていないカートに対するものです。何も変更されません。

顧客に PagBank payments are temporarily unavailable. Please choose another payment method. が表示される：現在のモードのトークンがないか、PagBank がトークンを拒否しました。

顧客に PagSeguro/PagBank only accepts payments in Brazilian Real (BRL). が表示される：カートが別の通貨になっています。

注文が PagBank payment on hold になっている：PagBank payment ブロックのメモを読み（注文ステータスを参照）、PagBank で金額を比較してから、注文を処理するか支払いを返金してください。

トークンに関するメッセージで返金が失敗する：支払いはサンドボックスか本番のどちらかで行われ、その環境のトークンがないか拒否されました。正しいトークンを入力して再試行してください。

アンインストール

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

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