VibeFox PagSeguro for WooCommerce — ヘルプ
要件
WordPress：6.0 以降。
WooCommerce：8.0 以降。インストールされ有効になっている必要があります。WooCommerce がないとプラグインは有効化できません。
PHP：8.0 以降。
通貨：ブラジル・レアル（BRL）。ストアの通貨（Pay for order ページでは注文の通貨）が BRL でない場合、チェックアウトでこの支払い方法は表示されません。
HTTPS：PagBank が支払い通知を送信できるように、サイトはインターネットから HTTPS でアクセスできる必要があります。
PagBank アカウント：実際の支払いには本番用トークン、テストにはサンドボックストークンが必要です。本番用トークン：PagBank アカウントにログインし、Venda online > Integrações を開いて Gerar token をクリックします。トークンは PagBank からメールで届きます。サンドボックス：PagBank の開発者ポータルでサンドボックスアカウントを作成し、そのトークンをコピーします。サンドボックスと本番のトークンは、それぞれの環境でのみ使えます。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ使用できます。
インストール
1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_pagseguro_gateway フォルダを /wp-content/plugins/ にアップロードすることもできます。
2. Activate をクリックします。
3. 設定を開きます。WooCommerce > Settings > Payments > PagSeguro / PagBank > Manage を開くか、プラグインページでプラグイン名の下にある Settings をクリックします。
4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。
5. サンドボックストークンを入力します。実際の支払いを受け付けるには、本番用トークンも入力します。
6. Enable / Disable をオンにして保存します。Sandbox Mode をオンにした状態でテスト決済を行い、その後オフにすると実際の支払いを受け付けます。
設定
すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > PagSeguro / PagBank。ページのタイトルの下には現在のモードが表示されます。SANDBOX MODE（決済は PagBank のサンドボックスで作成され、実際の請求は発生しません）または LIVE（決済は本番用トークンで作成されます）です。現在のモードのトークンが未入力の場合（その場合、チェックアウトでは支払い方法が非表示になります）や、ストア通貨が BRL でない場合には警告を表示します。支払い方法の一覧では、現在のモードのトークンが入力されるまで 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 の表示が出ます。注文のステータス確認と返金は、その注文の決済が作成されたときの環境とトークンを常に使います。初期値：オン。
Sandbox token：PagBank のサンドボックストークン。サンドボックスモードがオンの間に使われます。
Production token：PagBank の本番用トークン。サンドボックスモードがオフの間に使われます。秘密にしてください。
バージョン 1.0 の単一トークンは自動的に移行されます。サンドボックスモードがオンだった場合はサンドボックストークンになり、そうでない場合は本番用トークンのままになります。
支払い通知
すべての決済で、ステータスの変更を PagBank がどこへ通知するかが指定されるため、PagBank 側で設定することはありません。このセクションには通知 URL が表示されます。形式は次のとおりです：https://your-site/wc-api/webhook_wc_pagseguro/。このアドレスは、インターネットから HTTPS でアクセスできる必要があります。
x-authenticity-token ヘッダーを含む通知は、注文の環境のトークンで検証されます。署名が無効な通知は拒否されます。通知の本文そのものは信頼されません。プラグインは注文を変更する前に、必ず PagBank API からチェックアウトと PagBank の注文（ステータス、金額、通貨）を読み取ります。
詳細設定
Debug log：Log API requests and notifications をオンにすると、詳細が WooCommerce > Status > Logs に書き込まれます。ソースは wcp_pagseguro_gateway です。エラーは常に記録されます。ログにトークンや購入者のデータは含まれません。初期値：オフ。
Delete Data on Uninstall：Remove the gateway settings and logs when the plugin is deleted。初期値：オフ。
チェックアウト
購入者は支払い方法（初期値は PagSeguro / PagBank）を選んで注文します。プラグインは、注文の合計額と同額を BRL の 1 つの商品として PagBank のチェックアウトを作成します。商品名は Order # に注文番号とストア名を続けたものです。その後、購入者を PagBank の決済ページへ移動させます。Brazilian Market on WooCommerce プラグインのフィールドにある購入者の氏名、メールアドレス、CPF または CNPJ、ブラジルの電話番号は、ストアにあれば自動入力されます。購入者は PagBank のページでこれらを補完または修正できます。購入者は、お使いの PagBank アカウントで有効になっている支払い方法（クレジットカード、PIX、boleto など）で支払います。
決済ページは、WooCommerce の Hold stock タイマーが未払いの注文をキャンセルする 5 分前に期限切れになります（最短 10 分）。在庫を保持しない場合は 120 分後に期限切れになります。
支払い後、購入者はストアに戻ります。この戻りは通知と同じ方法で確認されます。プラグインは PagBank API から支払いを読み取ります。戻りだけで注文が支払い済みになることはありません。支払い済みの注文や、支払いの保留中（boleto、PIX、審査）の場合は注文受付ページに移動します。PagBank からまだ通知が届いていない場合は、通知によって注文が確定します。
支払いが完了しなかった場合、購入者は Pay for order ページに戻り、次のいずれかのメッセージが表示されます：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. 支払いがキャンセルされ、注文もそれに伴ってキャンセルされた場合は、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 が示した理由は、注文メモに追加されます。
この支払い方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の高性能注文保存（HPOS）に対応しています。
プラグインには、サイト上のカードフォーム、カードの保存、サブスクリプションや定期決済、分割決済、マーケットプレイスの機能はありません。支払い方法と分割払いは、お使いの PagBank アカウントで設定されたものが使われます。
注文と返金
注文ステータス
Pending payment：購入者は PagBank に移動しましたが、まだ支払っていません。メモには PagBank チェックアウト ID と環境が表示されます。支払いのないまま決済ページが期限切れになった場合は、その旨がメモに記録され、ステータスは変わりません。
Processing：支払いが確認されました。これは支払い後の WooCommerce の標準ステータスです。ダウンロード可能な仮想商品のみの注文は完了になります。注文メモには、金額、支払い方法、PagBank の請求 ID が表示されます。この請求 ID は注文のトランザクション ID でもあります。
On hold：boleto または PIX が発行され、支払いを待っている状態です。支払いが審査中です。カード決済は承認されたもののキャプチャされていません（PagBank でキャプチャしてください）。支払われた金額または通貨が注文と一致しません。または、WooCommerce が未払いの注文をキャンセルした後に支払いが届きました（在庫を確認してから注文を完了するか、PagBank で支払いを返金してください）。理由は注文メモに記載されます。
Failed：支払いが拒否されました。購入者は Pay for order ページから再度支払うことができます。
Cancelled：支払いがキャンセルされました。例：期限切れの boleto や PIX。
Refunded：PagBank のダッシュボードで支払い全額が返金されました。
各 PagBank ステータスは 1 回だけ適用されるため、通知や戻りが繰り返されても、メモ、メール、在庫の減算が追加されることはありません。すでに支払い済みの注文に 2 回目の支払いが届いた場合は、メモで PagBank から返金するよう通知されます。
返金
注文を開き、Refund をクリックして金額を入力し、Refund via PagSeguro / PagBank をクリックします（ボタンには支払い方法のタイトルが表示されます）。全額返金と一部返金に対応しています。返金は、支払いが行われた環境とトークンを使って送信されます。返金は PagBank が確認した場合にのみ記録されます。確認されない場合、WooCommerce は PagBank refund failed: ... や PagBank did not confirm the refund などのエラーを表示し、何も記録されません。boleto 決済の返金と PIX の一部返金には、PagBank のルールが適用されます。返金に成功すると、請求 ID とともに注文メモに追加されます。
PagBank のダッシュボードで行った返金は、WooCommerce の返金行としてはインポートされません。全額返金を行うと注文は返金済みになります。一部返金の場合は、返金額を記載したメモが追加され、返金を注文に手動で追加できます。
ライセンスキー
このプラグインは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > PagSeguro / PagBank ページの上部にあります。キーを License key に貼り付け、Activate をクリックします。ブロックには、ライセンスの有効期限日やお使いのドメインなどのステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインでのみ使用できます。サイトからキーを削除しても、そのドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、PagBank はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、(unlicensed — visible to admins only) と表示付きで支払い方法が引き続き表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインページと WooCommerce のページには通知が表示されます。既存の注文は影響を受けません。開始済みの支払いは引き続き確認され、返金も行えます。
ライセンスの期限が切れてもプラグインは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは自動的にバックグラウンドで再確認されます。
トラブルシューティング
チェックアウトに PagBank が表示されない：ライセンスが有効であること、Enable / Disable がオンであること、現在のモードのトークンが入力されていること（サンドボックスモードでは Sandbox token、ライブモードでは Production token）、ストア通貨が BRL であることを確認してください。設定ページには、いずれの場合も警告が表示されます。
支払いは完了したのに、注文が支払い待ちのままになる：PagBank からまだ支払いの報告がなく、購入者もストアに戻っていません。通知が届くと注文は更新されます。サイトがインターネットから HTTPS でアクセスできることを確認し、WooCommerce > Status > Logs（ソース wcp_pagseguro_gateway）を確認してください。
通知の応答が Invalid signature になる：x-authenticity-token が、注文が支払われた環境のトークンと一致していません。設定に正しいトークンが入っているか確認してください。
通知の応答が Verification failed, retry later になる：PagBank API に接続できない、注文の環境のトークンがない、または同じ時点で別のリクエストによって注文が更新されていた、のいずれかです。PagBank は通知を再送します。
通知の応答が Order not found になる：注文がこのストアに存在しない、または別の支払い方法で支払われています。何も変更されません。
購入者に This order is already being processed と表示される：通知または購入者の戻りが、同じ時点で注文を更新していました。購入者は少し待ってから再度お試しください。
購入者に PagBank payments are temporarily unavailable と表示される：現在のモードのトークンがないか、PagBank に拒否されています。
購入者に PagSeguro/PagBank only accepts payments in Brazilian Real (BRL) と表示される：注文が別の通貨になっています。
注文が On hold になり、Amount/currency does not match のメモが付く：PagBank が報告した支払いの金額または通貨が注文の合計と一致しません。たとえば、決済ページを作成した後に注文が編集された場合などです。PagBank で金額を照合し、注文を手動で完了するか返金してください。
トークンに関するメッセージが出て返金に失敗する：支払いはサンドボックスまたは本番で行われ、その環境のトークンがないか、拒否されています。正しいトークンを入力して、もう一度お試しください。
ライセンスブロックにエラーが表示される：ブロックのメッセージに従ってください。たとえば、キーが別のドメインですでに使われている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックします。サイトのアドレスを変更した場合は、Check now をクリックして新しいドメインでキーを有効にします。ライセンスサーバーに接続できない場合、プラグインは最後に確認されたステータスで動作を続けます。
アンインストール
プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定、プラグインのその他のオプション、ログは、Delete Data on Uninstall がオンになっている場合にのみ削除されます。それ以外の場合は、後で再インストールするために保持されます。既存の注文は、支払いメモ、トランザクション ID、PagBank のデータを保持します。
PagSeguro と PagBank は、それぞれの所有者の商標です。このプラグインは PagSeguro または PagBank と提携しておらず、両社から支持・推奨されてもいません。