VibeFox Iugu for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x まで。
PHP: 8.0 以降。古い PHP バージョンではモジュールのインストールを拒否します。
通貨: ブラジルレアル（BRL）。Iugu は BRL でのみ請求します。他の通貨のカートや、合計が R$ 1.00（Iugu の最低額）未満のカートでは、この支払い方法は表示されません。
Iugu アカウント: Iugu のダッシュボードから API トークンを 2 つ取得する必要があります。一方は "Test" 種別、もう一方は "Live" 種別です（設定を参照）。Iugu は両方に同じ API アドレスを使います。請求書がテストか実際のものかは、トークンによって決まります。Iugu で webhook を設定する必要はありません。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使えます。
インストール
1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox Iugu Gateway を探し、Configure をクリックしても構いません。
3. 設定ページ上部のライセンスブロックにある License key 欄に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. テストと本番の API トークンを入力し（設定を参照）、Test mode をオンのままにして、Enable / Disable をオンにし、Save をクリックします。
5. テスト注文を作成し、Iugu のテスト決済で Iugu のページから支払います。準備ができたら Test mode をオフにします。
インストール時に、モジュールは 2 つの注文ステータスを作成します。Awaiting Iugu payment と Iugu payment on hold です。PrestaShop は、すべての通貨、国、顧客グループ向けの新しい支払いモジュールを提供します。Payment > Preferences で制限できます。いずれの場合も、Iugu は BRL のカートにのみ提供されます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Iugu Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。フィールドの上には、TEST MODE（テスト用 API トークンで請求書を作成し、実際の請求は行わない）または LIVE が表示されます。有効なモードのトークンがない場合（この場合、チェックアウトで支払い方法が非表示になります）や、ストアの既定の通貨が BRL でない場合（この場合、他の通貨のカートには Iugu が提供されません）には、警告が表示されます。
Iugu
Enable / Disable: Enable Iugu payments で支払い方法のオン・オフを切り替えます。既定値: off。
Title: チェックアウトで購入者に表示される支払い方法の名前です。注文に保存される支払い方法名にもなります。既定値: Iugu。必須。
Description: チェックアウトで支払い方法の下に表示されるテキストです。既定値: Pay securely via Iugu. You will be redirected to complete your payment.
API 認証情報
Iugu Alia（alia.iugu.com）で API トークンを作成します：Settings > API integration > New。"Test" 種別のトークンと "Live" 種別のトークンをそれぞれ 1 つずつ作成します。
Test mode: テスト用 API トークンを使用するため、実際の請求は行われません。既定値: on。テストモードがオンの間、チェックアウトでは説明文の上に SANDBOX — Test mode enabled. No real charges. が表示されます。注文のステータス確認と返金は、その注文の請求書が作成されたモードのトークンを必ず使用します。そのため、モードを切り替えても古い注文は影響を受けません。
Test API token: "Test" 種別の Iugu API トークンです。テストモードがオンの間に使用されます。
Live API token: "Live" 種別（本番用）の Iugu API トークンです。テストモードがオフの間に使用されます。秘密にしてください。
保存済みのトークンは再表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。
Clear saved tokens: トークンにチェックを入れて Save をクリックすると削除されます。フィールドが空の場合は、保存済みの値が保持されます。
支払い通知
Notification URL: すべての請求書は、ステータスの変化をストアのこの URL に報告するよう Iugu に指示します。フレンドリー URL を有効にしていると、次のような形になります：https://your-shop/module/wcp_iugu_gateway/webhook。Iugu 側で設定することはありません。同じ URL を指すアカウント全体の追加トリガー（gatilho）があっても問題ありません。通知には、ストアが信頼する支払いデータは含まれません。注文を作成または変更する前に、請求書は必ず Iugu API から読み直されます（ステータス、金額、通貨）。
モジュールは、請求書のステータスを変えうる Iugu のイベントに反応します：invoice.status_changed、invoice.refund、invoice.released、invoice.dunning_action、invoices。それぞれについて、請求書を読み込み、そのステータスを適用します：
その他のイベントや、貴店が作成したのではない請求書には HTTP 200 で応答し、Iugu へのリクエストは行わずに無視します。通知がない場合、請求書が確認されるのは、購入者が Iugu のページからストアに戻ったときだけです。
詳細設定
Debug log: Iugu のリクエストと通知を、モジュールフォルダ内の logs/wc_igu_debug.log.php に書き込みます。このファイルは Web から開くことはできません。トークンと購入者のデータは記録されません。エラーと警告は、スイッチがオフでも常に書き込まれます。既定値: off。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Delete Data on Uninstall: オンにすると、モジュールをアンインストールしたときにゲートウェイの設定とログが削除されます。注文、Iugu の請求書の参照情報、返金、モジュールの注文ステータスは常に保持されるため、再インストール後も古い注文は引き続き機能します。既定値: off。
チェックアウト
決済ステップで、購入者は支払い方法（既定では Iugu）を選び、確定します。有効なメールアドレスが必要です。モジュールは、カートの合計金額に対する BRL の Iugu 請求書を、支払期限 3 日で作成し、購入者を Iugu の請求書ページへ案内します。そこで購入者は、貴店の Iugu アカウントで有効になっている方法（クレジットカード、boleto、PIX）で支払います。請求書には Order # とカート番号が表示されます。購入者の氏名とメールアドレスは Iugu に送信されます。住所の Identification number または VAT number の項目に値がある場合は、会社名と CPF/CNPJ も送信されます。電話番号と住所は、Iugu が受け付ける形式でのみ送信されます（ブラジルの電話番号、8 桁の CEP を持つブラジルの住所。番地は s/n として送信されます）。この時点ではまだ注文は存在しません。
支払い後、購入者は貴店に戻ります。注文が支払い済みとしてマークされるのは、Iugu が確認した後だけです。購入者が戻ったときと、Iugu が通知を送ったときに、請求書が Iugu API から読み込まれます。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。そこには Your payment with Iugu has been received. と表示されます。
購入者が boleto または PIX のコードを作成し、支払う前に戻った場合、注文は Awaiting Iugu payment で作成され、確認ページには Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. が表示されます。Iugu が入金を報告すると（通知によって、または購入者が戻りリンクを再度開いたときに）、注文は Payment accepted に移行します。購入者が戻った時点でまだ Iugu に接続できない場合は、Payment confirmation ページが表示され、We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. と、Check again ボタンおよび Back to checkout ボタンが表示されます。請求書がキャンセルされたか、支払われないまま期限切れになった注文では、確認ページに Your Iugu payment was not completed. Please contact us about this order. が表示されます。
注文が作成される前に請求書がキャンセルされたか期限切れになった場合、購入者はチェックアウトに戻り、The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. を目にします。カートは保持されます。購入者が再度支払うとき、金額とモードが変わっていなければ、モジュールは同じ未払いの請求書へ案内します。そうでない場合は、Iugu で古い請求書をキャンセルし、新しい請求書を作成します。これにより、同じカートが 2 つの未払い請求書で二重に支払われることはありません。古い請求書が後から支払われた場合でも、その支払いはカートと照合されます。
Iugu が請求書を作成できない場合、購入者は短いメッセージとともにチェックアウトに残ります。例：Iugu could not create the invoice: に理由と、請求情報を確認するよう求める文言が続きます。または Could not connect to Iugu. Please try again in a moment. 技術的な理由はログに書き込まれます。
通知 URL は、ストアがメンテナンスモードの間も機能し、貴店の国別制限によってブロックされることはありません。
モジュールが扱うのは 1 回限りの支払いだけです。サイト内のカードフォーム、保存済みカード、サブスクリプションや定期請求、carnê（分割払い用の支払い票）、分割払い、割賦設定はありません。割賦には Iugu のページの設定を使用してください。Iugu のページで提供される支払い方法は、モジュールの設定では選べません。Iugu アカウントで有効になっているすべての方法が提供されます。Payment error または Canceled の注文は、ストアから再度支払うことはできません。購入者は新しい注文をします。
注文と返金
注文ステータス
No order yet: 購入者は Iugu に案内されたが、まだ支払っていないか、Iugu がまだ支払いを確認していません。存在するのはカートだけです。
Payment accepted: Iugu が支払いを確認しました。支払いは Iugu の請求書 ID を取引 ID として記録され、メモには請求書 ID と支払い方法（クレジットカード、boleto、PIX）が表示されます。
Awaiting Iugu payment: 購入者は、発行済みの boleto または PIX を持って戻りました。Iugu が支払いを報告すると、注文は Payment accepted に移行します。
Iugu payment on hold: カード決済は承認されたものの、まだ売上確定（キャプチャ）されていません（Iugu で売上確定してください。Iugu が請求書の支払い済みを報告すると、注文は完了します）。または、決済が審査中である、請求書が一部のみ支払われた、チャージバックが申し立てられた、カートと異なる金額または通貨を Iugu が報告した（例：請求書の作成後にカートが変更された）、あるいは注文のキャンセル後に支払いが届いた、といった場合です。メモに理由が記載されています。注文を確認し、対応するか、支払いを返金してください。
Payment error: 支払い待ちの注文の請求書が、支払われないまま期限切れになりました。その後 Iugu が請求書を支払い済みと報告した場合、注文は Payment accepted に移行します。
Canceled: 支払い待ちの注文の請求書が Iugu でキャンセルされました。
Refunded: モジュール経由または Iugu のダッシュボードで、支払いが全額返金されました。
同じカートの別の請求書も支払われた場合、注文は変更されません。メモで、重複した支払いを Iugu で返金するよう求められます。
Iugu 支払いブロック
注文ページには Iugu payment ブロックが表示されます。内容は、Iugu の請求書 ID（Iugu の請求書へのリンク付き）、支払い方法、ステータス、Iugu が徴収した金額と返金された金額、テスト用請求書の Test mode バッジ、返金履歴、注文の Iugu notes です。
返金
Iugu payment ブロックで金額を入力します（まだ返金されていない金額が自動で入ります）。必要に応じて理由を入力し、Refund via Iugu をクリックします。確認の質問 Refund this amount through Iugu? This cannot be undone. に同意してください。注文を編集する権限が必要です。返金は、請求書が作成されたモードのトークンで送信されるため、そのトークンが設定されている必要があります。
返金額は、Iugu が請求書について実際に徴収した金額を基準とします。そのため、金額の不一致が発生した後は、注文合計ではなく、購入者が実際に支払った金額まで返金できます。支払い済みの請求書だけが返金可能で、Iugu 上でまだ返金可能な金額を超えることはできません。返金が完了とみなされるのは、Iugu が確認したときだけです。Iugu が返金を拒否した場合、または確認しない場合は、ブロックにエラーが表示され、返金は記録されません。成功した返金は、請求書 ID と理由とともに、返金履歴とメモに追加されます。全額返金の場合、注文は Refunded になります。一部返金の場合、ステータスは変わりません。返金は、Iugu が請求書を支払い済みと報告した後に利用できます。
モジュールはクレジットノート（credit slips）を作成しません。注文ページにある PrestaShop の標準の返金ボタンでは、Iugu を通じて返金されることはありません。
Iugu のダッシュボードで行った全額返金は、注文を Refunded にし、メモを追加します。ダッシュボードで行った一部返金は取り込まれません。
ライセンスキー
モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox Iugu Gateway のライセンスブロックは、Modules > Module Manager > VibeFox Iugu Gateway > Configure ページで設定より上にある最初のブロックです。License key にキーを入力し、Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限日やドメインなど）と、以下のボタンが表示されます：Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）。その下には Product: presta-payment-iugu の行と、Manage licenses and domains in your account のリンクがあり、これは vibefox.net のアカウントを開きます。キーを変更できるのは、このモジュールの Configure 権限を持つスタッフだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。
キーが受け付けられない場合、ブロックは理由を表示します。例：Key not found、This key belongs to another product、Domain limit reached、または License expired on と日付。ショップのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。
1 つのキーは 1 つのドメインで使えます。メインショップのドメインを指し、マルチストア構成でも同様です。ショップからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがない場合、チェックアウトで購入者には Iugu が表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、あなたが管理画面にログインしていることを認識しないため、支払い方法はあなたにも非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトで試すことはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された支払いは引き続き確認され、返金も機能します。
ライセンスの期限が切れても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面で作業している間に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Iugu が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、有効なモードのトークンが設定されていることを確認してください。テストモードでは Test API token、本番モードでは Live API token です。カートの通貨は BRL で、合計は R$ 1.00 以上である必要があります。Payment > Preferences で、モジュールが BRL 通貨、購入者の国、購入者のグループに対して許可されているか確認してください。トークンまたは通貨が誤っている場合、設定ページに警告が表示されます。
支払いは完了したが注文が作成されなかった: Iugu からの通知がストアに届かなかったか、確認できませんでした。Debug log をオンにして、モジュールのページにある Log 欄を確認してください。ストアが Notification URL でインターネットから到達可能であること、そして請求書が作成されたモードのトークンがまだ入力されていることを確認してください。購入者が支払い後にストアに戻ったときにも、請求書は確認されます。
Notification answers verification failed: その時点で、ネットワークエラー、誤ったトークン、請求書のモードのトークンが無いなどの理由により、請求書を Iugu API から読み取れませんでした。Iugu は通知を再試行します。
Notification answers busy: 同じ時刻に別のリクエストがカートを処理していた、または注文を作成できなかった（例：モジュールが無効になっている）ことを意味します。Iugu は通知を再試行します。ログに理由が表示されます。
Notification answers invalid invoice id: 通知に有効な請求書 ID がありませんでした。何も変更されません。
注文が Iugu payment on hold の状態: 注文ブロックの Iugu notes を確認してください。カード決済が売上確定を待っている、決済が審査中である、一部のみ支払われた、または異議が申し立てられた、支払われた金額がカートと一致しない、または注文のキャンセル後に支払いが届いた、といった状況です。
購入者に「Iugu payments are not available right now」と表示される: API トークンがない、または誤っています。有効なモードのトークンを確認してください。
購入者に「This order already has an Iugu payment that the store has to review」と表示される: カートの以前の請求書が、承認済み、審査中、または一部支払い済みですが、注文を作成できませんでした。Iugu で請求書を確認し、ログを確認してください。
返金に失敗する: ブロック内のメッセージを確認してください。boleto の支払いは Iugu 経由では返金できません。PIX の支払いは全額の返金のみ可能で、支払い済みの請求書のみ返金できます。メッセージが、支払いがテストモードまたは本番モードで行われたことを示しており、そのモードのトークンが設定されていない場合は、そのモードのトークンを入力してください。Iugu が返金を確認していない場合は、再試行する前に Iugu で請求書を確認してください。
開発者は、請求書のリクエストを変更できます。たとえば、actionWcpIuguInvoiceData フックで payable_with を使い、支払い方法を制限できます。
アンインストール
Modules > Module Manager に移動し、VibeFox Iugu Gateway の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete Data on Uninstall がオンの場合、ゲートウェイの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。Iugu の請求書の参照情報と返金、および注文ステータス Awaiting Iugu payment と Iugu payment on hold は常に保持されるため、以前に支払われた注文は引き続き返金でき、再インストール後も遅れて届いた通知が引き続き照合されます。既存の注文は、支払いメモと取引 ID を保持します。
Iugu は、その所有者の商標です。このモジュールは Iugu と提携しておらず、Iugu による推奨も受けていません。