VibeFox Iugu for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 8.0 以降、インストールおよび有効化済み。WooCommerce がない場合、プラグインは有効化できません。

PHP: 8.0 以降。

ストアの通貨: ブラジルレアル（BRL）。Iugu は BRL のみで請求します。ストア、または Pay for order ページの注文が別の通貨を使用している場合、および合計金額が R$ 1,00（Iugu の最低額）未満の場合、支払い方法は表示されません。

Iugu アカウント: Iugu のダッシュボードから API トークンを 2 つ取得する必要があります。1 つは "Test" タイプ、もう 1 つは "Live" タイプです（設定を参照）。Iugu は両方に同じ API アドレスを使用し、トークンによって請求書がテスト用か実際のものかが決まります。Iugu で Webhook を設定する必要はありません。

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

インストール

1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_iugu_gateway フォルダを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。

3. WooCommerce > Settings > General で、ストアの通貨をブラジルレアル（BRL）に設定します。

4. 設定を開きます：WooCommerce > Settings > Payments > Iugu > Manage。または、プラグインページでプラグイン名の下にある Settings をクリックします。

5. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。

6. テスト用と本番用の API トークンを入力し（設定を参照）、Test mode をオンのままにして、Enable / Disable をオンにして保存します。

7. テスト注文を行い、Iugu のテストカードで支払います。準備ができたら、Test mode のチェックを外します。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Iugu。ゲートウェイのタイトルの下に、TEST MODE（テスト用 API トークンで請求書が作成され、実際の請求は発生しません）または LIVE が表示されます。有効なモードのトークンがない場合（この場合、チェックアウトで支払い方法は非表示になります）や、ストアの通貨が BRL でない場合は警告が表示されます。支払い方法の一覧では、有効なモードのトークンが入力されるまで 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" タイプのトークンを 1 つと、"Live" タイプのトークンを 1 つ作成します。

Test mode: Use the test API token (no real charges)。デフォルト: on。テストモードがオンの間、チェックアウトには説明の上に SANDBOX — Test mode enabled. No real charges. が表示されます。注文のステータス確認と返金には、常にその請求書が作成されたモードのトークンが使われるため、モードを切り替えても古い注文には影響しません。

Test API token: "Test" タイプの Iugu API トークン。テストモードがオンの間に使用されます。

Live API token: "Live"（本番）タイプの Iugu API トークン。テストモードがオフの間に使用されます。秘密にしてください。

支払い通知

すべての請求書は、ステータスの変更を貴店の通知 URL に報告するよう Iugu に指示します。この URL は設定のこのセクションに表示されます。形式は https://your-site/wc-api/webhook_wc_iugu/ です。Iugu で設定することはありません。同じ URL を指すアカウント全体の追加トリガー（gatilho）があっても問題ありません。通知には、ストアが信頼するような支払いデータは含まれていません。注文を変更する前に、請求書は必ず Iugu API から読み直されます（ステータス、金額、通貨）。

プラグインは、請求書のステータスを変えうる Iugu のイベントに対応します：invoice.status_changed、invoice.refund、invoice.released、invoice.dunning_action、invoices。それぞれについて請求書を読み込み、そのステータスを適用します：

paid: 金額と通貨の確認後、注文は支払い済みになります。

authorized or in_analysis: カード決済はキャプチャ待ちか審査中です。注文は保留になります。

partially_paid: 請求書は一部のみ支払われました。注文は保留になります。

expired: 請求書は支払いのないまま期限切れになりました。注文は失敗となり、購入者は再度支払うことができます。

canceled: 請求書はキャンセルされました。注文はキャンセルされます。

refunded: 請求書は Iugu で返金されました。注文は返金済みになります。

chargeback: カード保有者が支払いに異議を申し立てました。支払い済みの注文は保留になります。

その他のイベントや、このストアの注文に属さない請求書には OK と応答され、無視されます。通知がない場合、注文は購入者が Iugu のページからストアに戻ったときにのみ確認されます。

詳細設定

Debug log: WooCommerce > Status > Logs の、ソース wcp_iugu_gateway で Log API requests and notifications。トークンや購入者データは含まれません。エラーは常に記録されます。デフォルト: off。

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted。デフォルト: off。

チェックアウト

購入者は支払い方法（デフォルトは Iugu）を選んで注文します。有効な請求先メールアドレスが必要です。プラグインは注文金額に対して BRL の Iugu 請求書を作成し、支払期限は 3 日とし、購入者を Iugu の請求書ページに案内します。そこで購入者は、Iugu アカウントで有効になっている方法（クレジットカード、boleto、PIX）で支払います。購入者の名前とメールアドレスは Iugu に渡されます。加えて、「Brazilian Market on WooCommerce」のチェックアウト項目に CPF/CNPJ、番地、地区があれば、それらも渡されます。電話番号と住所は、Iugu が受け付ける形式（ブラジルの電話番号、8 桁の CEP を含むブラジルの住所）でのみ送信されます。

支払い後、購入者は貴店の注文受付ページに戻ります。注文が支払い済みとなるのは、Iugu が確認した後だけです。請求書は、購入者が戻ったときと、Iugu が通知を送ったときに Iugu API から読み込まれます。購入者が boleto または PIX のコードを生成し、支払う前に戻った場合、Iugu が支払いを確認するまで注文は保留になります。WooCommerce の未払い注文タイマーは、Iugu の請求書がまだ未払いの注文をキャンセルしません。

請求書がキャンセルされたか期限切れになった場合でも注文の支払いが可能であれば、購入者は Pay for order ページに移動し、The Iugu invoice was not paid (it was canceled or has expired). You can pay the order again below. と表示されます。購入者が再度支払う際、金額が変わっていなければ、プラグインは同じ未払いの請求書に戻します。変わっている場合は、Iugu で古い請求書をキャンセルして新しい請求書を作成します。これにより、2 つの未払い請求書によって 1 つの注文が二重に支払われることを防ぎます。古い請求書が支払われた場合でも、その支払いは注文と照合されます。

Iugu が請求書を作成できない場合、購入者には短いメッセージが表示されます。例えば、理由と請求情報の確認を促す Iugu could not create the invoice:、または Could not connect to Iugu. Please try again in a moment. です。技術的な理由は注文メモとログに追加されます。

この支払い方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで使用できます。WooCommerce High-Performance Order Storage（HPOS）に対応しています。

プラグインが扱うのは 1 回限りの支払いだけです。サイト内のカードフォーム、保存済みカード、サブスクリプションや定期請求、carnê（分割払い用の支払い票）、分割払い、割賦設定はありません。分割払いには Iugu のページの設定を使用してください。Iugu のページに表示される支払い方法は、プラグインの設定では選択できません。Iugu アカウントで有効になっているすべての方法が提示されます。

注文と返金

注文ステータス

Pending payment: 請求書は作成済みですが、購入者はまだ支払っていません。

Processing or Completed: Iugu が支払いを確認しました。WooCommerce は支払い済みの注文として通常のステータスを設定します。注文メモには Iugu の請求書 ID と支払い方法（クレジットカード、boleto、PIX）が表示されます。トランザクション ID は Iugu の請求書 ID であり、注文画面では Iugu の請求書へのリンクになります。

On hold: 購入者が boleto または PIX を生成してストアに戻った（支払い待ち）、カード決済は承認済みだがキャプチャ前である（Iugu でキャプチャしてください。Iugu が請求書を支払い済みと報告すると注文は完了します）、支払いが審査中である、請求書が一部のみ支払われた、チャージバックが発生した、または支払われた金額か通貨が注文と一致しなかった。注文がキャンセルされた後に届いた支払いも、黙って再開されるのではなく保留になります。どの理由かは注文メモに示されます。

Failed: 請求書は支払いのないまま期限切れになりました。購入者は注文を再度支払うことができます。

Cancelled: 請求書は Iugu でキャンセルされました。

Refunded: 注文を支払った請求書は Iugu で返金されました。

同じ注文の別の請求書も支払われた場合、注文は再び変更されません。その支払いが重複していることを知らせるメモが表示され、Iugu で重複分を返金するよう求められます。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Iugu をクリックします。返金は、請求書が作成されたモードのトークンで送信されます。

Credit card: 全額または一部の返金。

PIX: 全額の返金のみ。

Boleto: Iugu を通じて返金することはできません。銀行振込で購入者に返金し、Refund via Iugu を使わずに手動で返金を記録してください。

返金できるのは支払い済みの請求書のみで、Iugu でまだ返金可能な金額を超えることはできません。返金は、Iugu が確認した場合にのみ完了とみなされます。Iugu が返金を拒否した、または確認しなかった場合、WooCommerce はエラーを表示し、返金は記録されません。返金が成功すると、請求書 ID と理由とともに注文メモに追加されます。

Iugu のダッシュボードで行われた全額返金は、注文を返金済みにします。ダッシュボードで行われた一部返金はインポートされません。

ライセンスキー

プラグインは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > Iugu のページ上部にあります。キーを License key に貼り付けて Activate をクリックします。ブロックには、ライセンスの有効期限日や貴店のドメインなどのステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。

1 つのキーは 1 つのドメインでのみ使えます。サイトからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウトで購入者に Iugu は表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、(unlicensed — visible to admins only) の表示付きで支払い方法が表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインのページと WooCommerce のページには通知が表示されます。既存の注文には影響しません。すでに開始された支払いは引き続き確認され、返金も機能します。

ライセンスの期限が切れても、プラグインは動作し続けますが、更新とサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。

トラブルシューティング

チェックアウトに Iugu が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、有効なモードのトークンが設定されていることを確認してください。テストモードでは Test API token、本番モードでは Live API token です。ストアの通貨は BRL で、注文合計は少なくとも R$ 1,00 である必要があります。トークンや通貨が誤っている場合、設定ページに警告が表示されます。

支払いは完了したが、注文が Pending payment のまま: Iugu からの通知がストアに届かなかったか、確認できませんでした。Debug log をオンにして、WooCommerce > Status > Logs のソース wcp_iugu_gateway を確認してください。設定に表示される通知 URL でサイトがインターネットから到達可能であること、請求書が作成されたモードのトークンがまだ入力されていることを確認してください。注文は、購入者が支払い後にストアに戻ったときにも確認されます。

Notification answers verification failed: ネットワークエラーや誤ったトークンなどの理由で、その時点では Iugu API から請求書を読み込めませんでした。Iugu は通知を再送します。

Notification answers invalid invoice id: 通知に有効な請求書 ID がありませんでした。何も変更されません。

注文が On hold になっている: 注文メモを確認してください。boleto または PIX がまだ未払い、カード決済がキャプチャ待ち、支払いが審査中、一部のみ支払い済みまたは異議申し立て中、支払われた金額が注文と一致しなかった、または注文のキャンセル後に支払いが届いたことが考えられます。

購入者に "Iugu payments are not available right now" と表示される: API トークンがないか、誤っています。有効なモードのトークンを確認してください。

返金が失敗する: メッセージを確認してください。boleto の支払いは Iugu で返金できず、PIX の支払いは全額のみ返金でき、支払い済みの請求書のみ返金できます。Iugu が返金を確認しなかった場合は、再試行する前に Iugu で請求書を確認してください。

ライセンスブロックにエラーが表示される: ブロック内のメッセージに従ってください。例えば、キーが別のドメインですでに使われている場合は、vibefox.net のアカウントで枠を解放してから Check now をクリックしてください。サイトのアドレスが変わった場合は、Check now をクリックして新しいドメインでキーを有効にしてください。ライセンスサーバーに接続できない場合、プラグインは最後に確認できたステータスで動作し続けます。

開発者は、請求書のリクエストを変更できます。例えば、payable_with で支払い方法を制限したり、wc_igu_invoice_data フィルターを使用したりできます。

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。完全に削除するには、無効化してから Plugins ページで削除してください。このプラグインのライセンスキーとライセンスのステータスは、常に削除されます。ゲートウェイの設定とログは、Delete Data on Uninstall がオンになっている場合にのみ削除されます。それ以外の場合は、後で再インストールする際のために残ります。既存の注文は、支払いメモとトランザクション ID を保持します。

Iugu は、それぞれの所有者の商標です。本プラグインは Iugu との提携や Iugu による推奨を受けていません。