VibeFox Pagar.me for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 ～ 9.x。

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

通貨: ブラジル・レアル（BRL）。それ以外の通貨のカートでは、決済手段は表示されません。

Pagar.me アカウント: Pagar.me アカウントの秘密鍵が必要です。テスト用キー（sk_test_...）と、本番移行時に使う本番用キー（sk_...）です。これらは Pagar.me のダッシュボードの Development > Keys にあります。使用するのは秘密鍵のみで、公開鍵（pk_...）は不要です。Pagar.me アカウントで有効になっている決済手段のみを提供できます。

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

インストール

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

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

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

4. テスト用の秘密鍵を入力します。本番に移行する際は、本番用の秘密鍵を入力します。

5. Pagar.me のダッシュボードで、設定に表示される URL を使ってウェブフックを作成します（設定を参照）。

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

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Pagar.me Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。項目の上には現在のモードが表示されます：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: テスト用の秘密鍵を使用します。実際の請求は発生しません。オンの間、お客様には決済手段の下に TEST MODE — Use test credentials. No real charges. と表示されます。注文のステータス確認や返金は、その注文の支払いが作成されたモードの鍵を常に使用します。既定値：オン。

Test secret key: Pagar.me のテスト用秘密鍵（sk_test_...）。テストモードがオンの間に使用されます。

Live secret key: Pagar.me の本番用秘密鍵（sk_...）。テストモードがオフのときに使用されます。機密情報として管理してください。

保存された鍵は再表示されません。項目は空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved secret keys: 鍵にチェックを入れて Save をクリックすると削除されます。空欄の場合は保存済みの値が維持されます。

決済ページ

Payment methods: Pagar.me の決済ページで提供される決済手段です。Pagar.me アカウントで有効になっている決済手段のみを選択してください。何もチェックされていない場合は、既定の決済手段が使用されます。既定値：Credit card, PIX and Boleto。

Boleto due in (days): boleto の支払期限までの日数（1 ～ 30）です。Pagar.me が支払いを確認するまで、注文は Awaiting Pagar.me payment のままになります。既定値：3。これ以外の値は保存時に Boleto due in (days): enter a number from 1 to 30. と表示されて拒否されます。

決済通知（ウェブフック）

Pagar.me のダッシュボードで Settings > Webhooks を開き、このセクションの Webhook URL に表示される URL を使ってウェブフックを作成します。フレンドリー URL の場合、次のような形式になります：https://your-shop/module/wcp_pagarme_gateway/webhook。/en/ のような言語コードが付く場合もあります。設定に表示されたとおりに正確にコピーしてください。

次のイベントを選択します（このセクションにも一覧があります）：

ウェブフックにパスワードや署名は不要です。その内容は信頼されません。ストアが使うのは、そこに含まれる Pagar.me の注文 ID のみで、その注文は作成されたモードの鍵を使って Pagar.me API から読み取られます。同じ Pagar.me アカウント上の他のストアの注文に関する通知は無視されます。ウェブフックがない場合、後から行われた PIX と boleto の支払いは、お客様がストアに戻ったときにのみ確認されます。

詳細設定

Debug log: API のリクエストと通知を、モジュールフォルダー内の logs/wc_pgm_debug.log.php に記録します。このファイルは Web から開くことはできません。エラーと警告は常に記録されます。鍵とお客様のデータは記録されません。既定値：オフ。

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

Delete Data on Uninstall: オンにすると、モジュールのアンインストール時にゲートウェイの設定とログが削除されます。注文、その Pagar.me の支払いデータ（返金に必要）、および注文ステータスは保持されます。既定値：オフ。

チェックアウト

決済ステップで、お客様は決済手段（既定では Pagar.me）を選択して確定します。有効なメールアドレスが必要です。モジュールは、BRL でのカート合計額に対する Pagar.me 注文を作成します。カートの商品明細、送料、ギフトラッピングを含みます（カートに割引がある場合は、カート番号を含む 1 行の Order # になります）。そのうえで、お客様を Pagar.me の決済ページに移動させます。この時点では、ストアにはまだ注文が存在しません。

お客様の氏名とメールアドレスは Pagar.me に渡されます。CPF または CNPJ は、住所の Identification number 項目、または VAT number から取得されます。ブラジルの携帯電話番号も渡されます。請求先住所は、8 桁の CEP と州を含むブラジルの住所の場合にのみ渡されます。PrestaShop には既定でブラジルの州がないため、お客様は通常、Pagar.me のページで住所を入力します。CPF または CNPJ がない場合、お客様はそこで入力します。

支払い後、お客様はストアに戻ります。注文が支払い済みとしてマークされるのは、Pagar.me が確認した後だけです。ストアは API から Pagar.me の注文を読み取り、支払われた金額と通貨がカートと一致する必要があります。カード、PIX、boleto の支払いが完了すると、注文は Payment accepted として作成され、お客様には Your payment with Pagar.me has been received. と表示される標準の注文確認ページが表示されます。発行済みで、まだ支払われていない PIX または boleto の場合、注文は Awaiting Pagar.me payment として作成され、ページには Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. と表示されます。戻るたびに Pagar.me の注文が再度読み取られるため、ウェブフックが届いていなくても、その間に支払われた PIX または boleto は反映されます。このような注文の支払いが失敗または期限切れになった場合、ページには Your Pagar.me payment was not completed. Please contact us about this 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. です。カートは保持されます。注文がすでに存在し、その支払いが失敗または期限切れになった場合のメッセージは、The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. です。Pagar.me に接続できない場合は、Payment confirmation ページが表示され、お客様に再度支払わないよう求め、Check again と Back to checkout を提示します。

お客様が再度支払う場合、金額とモードが同じであれば、開いている Pagar.me の決済ページが再利用されます。異なる場合は、新しいページを作成する前に Pagar.me 側で閉じられます。前回の試行がその間に支払われた場合、または PIX か boleto がまだ支払いを待っている場合は、新たに支払いを求めることなく注文が作成されます。前回のページを閉じられない場合は、カートに紐付いたままになるため、そのページで行われた支払いも記録されます。

Pagar.me が支払いを開始できない場合、お客様はチェックアウトに留まり、Could not connect to Pagar.me. Please try again in a moment. などの短いメッセージ、または請求情報が無効であることを示す Pagar.me のメッセージが表示されます。技術的な理由はログに記録されます。

ウェブフックは、ストアがメンテナンスモードの間も動作し、ストアの国別制限によってブロックされません。

本モジュールは、チェックアウト内にカードフォームを表示せず、保存済みカード、サブスクリプションや定期決済、分割払いのルール、分割決済（マーケットプレイス）、オーソリのみのカード決済、Pagar.me Hub 連携には対応していません。

注文と返金

注文ステータス

No order yet: お客様は Pagar.me に移動しましたが、まだ支払いも PIX または boleto の発行も行われていません。カートのみが存在します。

Payment accepted: 支払いが確認されました。支払いは、トランザクション ID として Pagar.me の注文 ID（or_...）とともに記録され、メモには Pagar.me の注文と決済手段が表示されます。

Awaiting Pagar.me payment: PIX または boleto が発行され（またはカード決済が審査中で）、支払いを待っています。Pagar.me が支払いを確認すると、注文は Payment accepted に移行します。

Pagar.me payment on hold: boleto が一部しか支払われていない場合；支払われた金額または通貨が注文と異なる場合（例：支払い開始後にカートが変更された）；キャンセル後に支払いが届いた場合；支払い済みの注文に対してチャージバックが発生した場合。メモに理由が説明されます。注文を確認して処理するか、支払いを返金してください。

Payment error: 待機中または保留中の注文の支払いが失敗したか、その Pagar.me 注文がキャンセルまたは期限切れになりました（例：未払いの boleto）。Pagar.me が後で支払いを報告した場合でも、注文は Payment accepted に移行します。

Refunded: モジュールを通じて支払いが全額返金されたか、Pagar.me 上で返金またはキャンセルされました。

各 Pagar.me ステータスは 1 回だけ適用されるため、ウェブフックや戻りが繰り返されても、メモや支払いが追加されることはありません。同じカートの 2 つ目の Pagar.me 注文が支払われた場合、メモで重複分を Pagar.me のダッシュボードから返金するよう求められます。

Pagar.me 決済ブロック

注文ページには Pagar.me payment ブロックが表示され、Pagar.me の注文 ID と請求 ID、決済手段、ステータス、支払済み額と返金済み額、テスト決済用の Test mode バッジ、返金履歴、注文の Pagar.me notes が含まれます。

返金

Pagar.me payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Pagar.me をクリックします。確認の質問 Refund this amount through Pagar.me? This cannot be undone. に同意してください。カードと PIX の支払いについて、全額返金と一部返金に対応しています。注文を編集する権限が必要です。返金できるのは、Pagar.me が実際に受け取った金額までです。そのため、金額の不一致があった後の上限は、注文合計ではなくお客様が支払った金額になります。返金は、支払いが行われたモードの鍵を使って送信されるため、そのモードの秘密鍵が設定されている必要があります。返金は、Pagar.me が確認した場合にのみ記録されます。そうでない場合、ブロックにはエラーが表示されます（例：Pagar.me refused the refund: ... または Pagar.me did not confirm the refund）。このとき返金は記録されません。返金が成功すると、請求 ID とともに返金履歴とメモに追加されます。全額返金すると、注文は Refunded になります。一部返金では、ステータスは変わりません。返金は、Pagar.me が支払いを報告した後に利用できます。

boleto の支払いは、お客様の銀行口座に対してのみ返金できます。Pagar.me のダッシュボードで返金してから、PrestaShop で返金を手動で記録してください。

本モジュールはクレジットスリップを作成しません。注文ページにある PrestaShop の標準の返金ボタンでは、Pagar.me を通じて返金されません。

Pagar.me のダッシュボードで行われた全額返金またはキャンセルは、ウェブフックを通じて届き、注文を Refunded にしてメモを追加します。チャージバックはメモを追加し、支払い済みの注文を Pagar.me payment on hold にします。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Pagar.me が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードの秘密鍵（テストモードでは Test secret key、本番モードでは Live secret key）が設定されていること、カートの通貨が BRL であることを確認してください。鍵が未入力の場合、設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、お客様の国、お客様のグループに対してモジュールが許可されているか確認してください。

支払いは完了したが、注文が作成されない、または注文が Awaiting Pagar.me payment のままになる: ウェブフックが機能していません。Pagar.me のダッシュボードで、使用しているアカウントとモードにウェブフックが存在すること、その URL が Webhook URL に表示されたものと完全に一致すること、上記のイベントがすべて選択されていることを確認してください。注文は、お客様がストアに戻るたびにも確認されます。

ウェブフックが verification failed, retry later と応答する: ストアは API から Pagar.me の注文を読み取れませんでした。たとえば、そのモードの鍵が未入力か、API が応答しなかった場合です。Pagar.me はウェブフックを再試行します。

ウェブフックが busy と応答する: 同時に別のリクエストによってカートが更新されていたか、注文を作成できませんでした（たとえば、モジュールが無効になっている場合）。Pagar.me はウェブフックを再試行します。理由を確認するには Debug log をオンにしてください。

ウェブフックが unknown order と応答する: その Pagar.me 注文は、このストアによって作成されたものではありません（例：同じアカウント上の別のストアの注文）。何も変更されません。

お客様に Pagar.me payments are not available right now と表示される: 秘密鍵が間違っているか、未入力です。現在のモードの鍵を確認してください。

お客様に Pagar.me could not start the payment と表示される: Pagar.me が請求情報を拒否しました。たとえば、住所の Identification number 項目にある CPF です。メッセージに問題が示されます。詳しい理由はログにあります。

お客様に Pagar.me only supports payments in Brazilian Real (BRL) と表示される: カートが別の通貨になっています。

お客様に This order already has a Pagar.me payment that the store has to review と表示される: このカートの以前の支払いについて、確認が必要です。Pagar.me のダッシュボードとログを確認してください。

支払い後に注文が Pagar.me payment on hold になる: Pagar.me payment ブロックのメモを確認してから（注文ステータスを参照）、注文を処理するか支払いを返金してください。

boleto の返金が失敗する: boleto の支払いは API 経由では返金できません。Pagar.me のダッシュボードで返金し、返金を手動で記録してください。

モードに関するメッセージが表示されて返金が失敗する: 支払いはテストモードまたは本番モードで行われましたが、そのモードの秘密鍵が設定されていません。鍵を入力してから、もう一度お試しください。

開発者は、送信前に actionWcpPagarmeOrderData フックを使って Pagar.me の注文データを変更できます。

アンインストール

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

Pagar.me は、それぞれの所有者の商標です。本モジュールは Pagar.me と提携しておらず、Pagar.me の承認も受けていません。