VibeFox Pagar.me for WooCommerce — ヘルプ
要件
WordPress: 6.0 以降。
WooCommerce: 8.0 以降。インストールされて有効になっている必要があります。WooCommerce がないとプラグインは有効化できません。
PHP: 8.0 以降。
通貨: ブラジル・レアル（BRL）。ストアの通貨（Pay for order ページでは注文の通貨）が BRL でない場合、決済方法は表示されません。
Pagar.me アカウント: Pagar.me アカウントの秘密鍵が必要です。テスト用キー（sk_test_...）と、本番稼働時に使用する本番用キー（sk_...）です。これらは Pagar.me のダッシュボードの Development > Keys にあります。使用するのは秘密鍵のみで、公開鍵（pk_...）は不要です。提供できるのは、Pagar.me アカウントで有効になっている決済手段のみです。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_pagarme_gateway フォルダを /wp-content/plugins/ にアップロードすることもできます。
2. Activate をクリックします。
3. 設定を開きます：WooCommerce > Settings > Payments > Pagar.me > Manage。または、プラグインの一覧画面でプラグイン名の下にある Settings をクリックします。
4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。
5. テスト用の秘密鍵を入力し、本番稼働時には本番用の秘密鍵を入力します。
6. Pagar.me のダッシュボードで、設定に表示された URL を使ってウェブフックを作成します（「設定」を参照）。
7. Enable / Disable をオンにして保存します。Test mode をオンにした状態でテスト決済を行い、その後オフにして実際の決済を受け付けます。
設定
すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Pagar.me。タイトルの下には現在のモードが表示されます：TEST MODE（テスト用の秘密鍵で決済が作成され、実際の請求は発生しません）または LIVE。現在のモードの秘密鍵がない場合（その場合、決済方法はチェックアウトで非表示になります）、テスト用キーが sk_test_ で始まらない場合、本番用キーが sk_ で始まらないか、テスト用キーである場合、ストアの通貨が BRL でない場合に警告が表示されます。決済方法の一覧では、現在のモードのキーが入力されるまで Pagar.me にセットアップが必要と表示され、テストモードの間はテストモードのバッジが表示されます。
一般
Enable / Disable: Enable Pagar.me payments は決済方法をオンまたはオフにします。初期値：オフ。
Title: 購入者がチェックアウトで目にする決済方法の名称。初期値：Pagar.me。
Description: チェックアウトで決済方法の下に表示されるテキスト。初期値：Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.
API キー
Pagar.me のダッシュボード（Development > Keys）から秘密鍵をコピーします。Pagar.me はテスト決済と本番決済で同じ API アドレスを使用します。決済がテストか実際のものかは、キーによって決まります。
Test mode: Use the test secret key (no real charges)。テストモードがオンの間は、チェックアウトに TEST MODE の表示が出ます。注文のステータス確認や返金は、その支払いが行われたモードのキーを常に使用します。初期値：オン。
Test secret key: Pagar.me のテスト用秘密鍵（sk_test_...）。テストモードがオンの間に使用されます。
Live secret key: Pagar.me の本番用秘密鍵（sk_...）。テストモードがオフの間に使用されます。秘密にしてください。
バージョン 1.0 の単一の秘密鍵は自動的に移行されます。テスト用キーは Test secret key に移され、テストモードがオンになります。それ以外の場合は本番用キーのままとなり、テストモードはオフになります。
決済ページ
Payment methods: Pagar.me の決済ページで提供される決済手段。Pagar.me アカウントで有効になっているものだけを選択してください。初期値：Credit card、PIX、Boleto。
Boleto due in (days): boleto の支払期限までの日数（1 ～ 30）。Pagar.me が支払いを確認するまで、注文は On hold のままです。初期値：3。
決済通知（ウェブフック）
Pagar.me のダッシュボードで Settings > Webhooks を開き、このセクションに表示される URL でウェブフックを作成します。URL は https://your-site/wc-api/webhook_wc_pagarme/ のような形式です。設定に表示されたとおりに正確にコピーしてください。
次のイベントを選択します：
ウェブフックにパスワードや署名は不要です。その内容が信頼されることはありません。ストアは、そこから Pagar.me の注文 ID だけを取り出し、作成されたモードのキーを使って Pagar.me API からその注文を読み取ります。同じ Pagar.me アカウント内の他のストアの注文に関する通知は無視されます。ウェブフックがない場合、後で行われた PIX や boleto の支払いは、購入者がストアに戻ったときにのみ確認されます。
詳細設定
Debug log: Log API requests and notifications は詳細を WooCommerce > Status > Logs に、ソース wcp_pagarme_gateway として書き込みます。エラーは常に記録されます。ログにはキーや購入者データは含まれません。初期値：オフ。
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted。初期値：オフ。
チェックアウト
購入者は決済方法（初期値は Pagar.me）を選択して注文を確定します。有効な請求先メールアドレスが必要です。プラグインは、注文合計に対する BRL 建ての Pagar.me 注文を作成し（注文明細、配送料、手数料を含みます。明細を正確に合計できない場合は、注文番号を含む 1 行の Order # にまとめます）、購入者を Pagar.me の決済ページに移動させます。購入者の名前、メールアドレス、ブラジルの場合は電話番号と請求先住所が Pagar.me に渡されます。CPF または CNPJ は、Brazilian Market on WooCommerce プラグインの項目が存在する場合にそこから取得されます。存在しない場合、購入者は Pagar.me のページで入力します。
支払い後、購入者はストアに戻ります。注文は、Pagar.me が確認してから初めて支払い済みになります。ストアは API から Pagar.me の注文を読み取り、支払われた金額と通貨は注文と一致している必要があります。支払い済みのカード決済、PIX、または boleto により、注文は支払い済みになります。発行されたものの未払いの PIX や boleto は、Pagar.me がウェブフックで支払いを確認するまで注文を On hold にします。
購入者が支払わずに戻った場合、または決済が拒否・キャンセルされた場合、購入者は Pay for order ページに移動し、The Pagar.me payment was not completed. You can pay the order below. または The Pagar.me payment was declined or canceled. You can try again below. と表示されます。
購入者が再度支払う場合、金額とモードが同じであれば、開いている Pagar.me の決済ページが再利用されます。そうでなければ、新しいページを作成する前に Pagar.me で閉じられます。以前の試行がその間に支払われていた場合、または PIX や boleto がまだ待機中の場合は、再度支払うことなく注文が更新されます。以前のページを閉じられない場合、そのページは注文に紐付いたままとなるため、そこで行われた支払いも記録されます。
Pagar.me が決済を開始できない場合、購入者には Could not connect to Pagar.me. Please try again in a moment. などの短いメッセージ、または請求先情報が無効であることを示す Pagar.me のメッセージが表示されます。技術的な理由は注文メモに追加されます。
この決済方法は、クラシックチェックアウト、Checkout ブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage（HPOS）に対応しています。
本プラグインは、チェックアウト内にカードフォームを表示せず、保存済みカード、サブスクリプションや定期決済、分割払いのルール、分割決済（マーケットプレイス）、オーソリのみのカード決済、Pagar.me Hub 連携には対応していません。
注文と返金
注文ステータス
Pending payment: 購入者は Pagar.me に移動しましたが、まだ支払っていないか、PIX や boleto を発行していません。メモには Pagar.me の注文 ID とモードが表示されます。
Processing: 決済が確認されました。これは支払い後の WooCommerce の標準ステータスです。ダウンロード可能な仮想商品のみの注文は、完了（Completed）になります。注文メモには Pagar.me の注文 ID と決済方法が表示されます。トランザクション ID は Pagar.me の注文 ID（or_...）です。
On hold: PIX または boleto が発行され（またはカード決済が審査中で）、支払いを待っています。boleto は一部のみ支払われた、支払われた金額または通貨が注文と異なる、注文のキャンセル後に支払いが届いた、購入者が別の決済方法に切り替えた後に Pagar.me で注文が支払われた、支払い済みの注文にチャージバックが発生した、などのケースです。注文メモで理由が説明されます。注文を確認して Processing に設定するか、Pagar.me で返金してください。
Failed: 決済が失敗したか、Pagar.me の注文がキャンセルまたは期限切れになりました（例：未払いの boleto）。未払い注文の最新の試行だけが、注文を Failed にできます。購入者は再度支払うことができます。
Refunded: 決済が Pagar.me で返金またはキャンセルされました。
各 Pagar.me ステータスは 1 回だけ適用されるため、ウェブフックや戻りが繰り返されても、メモ、メール、在庫の減算が重複することはありません。支払い済みの注文が保留や失敗に戻ることはなく、キャンセルされたか返金された注文が再び開かれることもありません。同じ WooCommerce 注文の 2 つ目の Pagar.me 注文が支払われた場合、メモによって Pagar.me のダッシュボードで重複分を返金するよう通知されます。
返金
注文を開き、Refund をクリックして金額を入力し、Refund via Pagar.me をクリックします（ボタンには決済方法のタイトルが表示されます）。カードと PIX の決済については、Pagar.me でまだ返金可能な金額の範囲内で、全額および一部の返金に対応しています。返金は、決済が行われたモードのキーで送信されます。返金は Pagar.me が確認した場合にのみ記録されます。そうでない場合、WooCommerce は Pagar.me refused the refund: ... や Pagar.me did not confirm the refund などのエラーを表示し、返金は記録されません。成功した返金は、請求 ID とともに注文メモに追加されます。
boleto の支払いは、購入者の銀行口座にのみ返金できます。Pagar.me のダッシュボードで返金し、その後 Refund via Pagar.me を使わずに、WooCommerce で返金を手動で記録してください。
Pagar.me のダッシュボードで行われた全額返金またはキャンセルは、ウェブフックで通知され、注文を Refunded に設定します。チャージバックはメモを追加し、Processing または Completed の注文を On hold にします。
ライセンスキー
このプラグインは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > Pagar.me の上部にあります。キーを License key に貼り付けて Activate をクリックします。ブロックには、ライセンスが有効な期限やドメインなどのステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、そのドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで Pagar.me は購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、決済方法が (unlicensed — visible to admins only) と表示された状態で引き続き表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインの一覧ページと WooCommerce のページには通知が表示されます。既存の注文には影響しません。すでに開始された決済は引き続き確認され、返金も行えます。
ライセンスの有効期限が切れてもプラグインは動作し続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。
トラブルシューティング
チェックアウトに Pagar.me が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードの秘密鍵（テストモードでは Test secret key、本番モードでは Live secret key）が設定されていること、ストアの通貨が BRL であることを確認してください。設定ページは、いずれの場合も警告を表示します。
決済は完了したのに注文が Pending payment または On hold のまま: ウェブフックが機能していません。Pagar.me のダッシュボードで、使用しているアカウントとモードのウェブフックが存在すること、その URL が設定に表示されたものと正確に一致すること、上に記載したイベントが選択されていることを確認してください。購入者がストアに戻ったときにも注文は確認されます。
ウェブフックが verification failed, retry later と応答する: ストアは API から Pagar.me の注文を読み取れませんでした。たとえば、そのモードのキーがない、または API が応答しなかった場合です。Pagar.me はウェブフックを再試行します。
ウェブフックが busy, retry later と応答する: 注文は別のリクエストによって同時に更新されていました。Pagar.me はウェブフックを再試行します。
ウェブフックが unknown order と応答する: その Pagar.me の注文は、このストアが作成したものではありません（同じアカウント内の別のショップの注文など）。何も変更されません。
購入者に This order is already being processed と表示される: ウェブフックまたは購入者の戻りが、同時に注文を更新していました。購入者は少し待ってから再試行できます。
購入者に Pagar.me payments are not available right now と表示される: 秘密鍵が間違っているか、ありません。現在のモードのキーを確認してください。
購入者に Pagar.me could not start the payment と表示される: Pagar.me が請求先情報を拒否しました。メッセージに問題が示されます。詳細な理由は注文メモにあります。
購入者に Pagar.me only supports payments in Brazilian Real (BRL) と表示される: 注文が別の通貨になっています（通貨切替プラグインなどが原因の場合があります）。
支払い後に注文が On hold になる: 注文メモを読んでください。PIX や boleto が支払いを待っている、支払われた金額または通貨が異なっていた、またはキャンセル後に支払いが届いた、のいずれかです。
boleto の返金が失敗する: boleto の支払いは API 経由では返金できません。Pagar.me のダッシュボードで返金し、手動で記録してください。
ライセンスブロックにエラーが表示される: ブロック内のメッセージに従ってください。たとえば、キーが別のドメインで既に使用されている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックしてください。サイトのアドレスが変わった場合は、Check now をクリックして新しいドメインでキーを有効にしてください。ライセンスサーバーに接続できない場合、プラグインは最後に確認されたステータスで動作を続けます。
アンインストール
プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイの設定とプラグインのログは、Delete data on uninstall がオンの場合にのみ削除されます。それ以外の場合は、後で再インストールする際のために残ります。既存の注文は、決済メモ、トランザクション ID、Pagar.me のデータを保持します。
Pagar.me は各所有者の商標です。本プラグインは Pagar.me と提携しておらず、Pagar.me の承認も受けていません。