VibeFox Xendit for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 8.0 以降。インストールされ、有効になっていること。WooCommerce がないとプラグインは有効化できません。

PHP: 8.0 以降。

ストア通貨: IDR、PHP、VND、THB、MYR、USD、SGD。それ以外の通貨では決済方法は表示されません。実際に利用できる決済チャネルと通貨は、Xendit アカウントによって異なります。

Xendit アカウント: テストモード用には Money-in（請求書）への書き込み権限を持つシークレット API キーが、本番モード用には別のキーが必要です。また、各モードのウェブフック検証トークンも必要です（「設定」を参照）。使用するのはシークレットキーと検証トークンだけです。購入者は Xendit がホストする請求書ページで支払うため、公開キーは不要です。

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

インストール

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

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

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

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

5. Xendit のシークレットキーを貼り付け、Xendit Dashboard でウェブフック URL を設定し、検証トークンを貼り付けます（「設定」を参照）。

6. Enable/Disable をオンにします。テストモードでテスト注文を行い、実際の支払いを受け付けるには Test Mode のチェックを外します。

設定

すべての設定は 1 ページにまとまっています: WooCommerce > Settings > Payments > Xendit。フィールドの上のバナーに、現在有効なモードが表示されます。TEST MODE（テスト用シークレットキーで請求書が作成され、実際の料金は請求されません）または LIVE MODE（本番用シークレットキーで請求書が作成され、顧客に請求されます）。有効なモードのシークレットキーがない場合、またはプレフィックスが正しくない場合（その場合、チェックアウトで決済方法が非表示になります）、そして有効なモードのウェブフック検証トークンが空の場合（Xendit からの通知が拒否されるため、購入者がストアに戻ったときにだけ注文が更新されます）、バナーで警告されます。決済方法の一覧では、有効なモードに有効なシークレットキーが設定されるまで、Xendit は設定が必要として表示されます。

一般

Enable/Disable: Enable Xendit は決済方法をオンまたはオフにします。デフォルト: オフ。

Title: チェックアウトで購入者に表示される決済方法の名前。デフォルト: Xendit。

Description: チェックアウトで決済方法の下に表示されるテキスト。デフォルト: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

API キー

Xendit Dashboard > Settings > Developers > API keys で、Money-in（請求書）への書き込み権限を持つシークレット API キーを作成します。テストモードで 1 回、本番モードで 1 回作成します。キーによって請求書の作成先が決まります。保存時、プレフィックスがそのフィールドと一致しないキーは保存されず、ページには例えば Test secret key was not saved: it must start with xnd_development_ と表示されます。その他の設定は保存されます。

Test Mode: Enable test mode はテスト用シークレットキーで請求書を作成するため、実際の料金は請求されません。デフォルト: オン。チェックを外すと、本番用シークレットキーで実際の支払いを受け付けます。

Test Secret Key: Xendit テストモードのシークレットキー。xnd_development_ で始まります。

Live Secret Key: Xendit 本番モードのシークレットキー。xnd_production_ で始まります。

ウェブフック

ウェブフックは、請求書が支払われたことをストアに通知します。Xendit Dashboard > Settings > Developers > Webhooks で、設定のこのセクションに表示される URL を、テストモードと本番モードの両方について、Invoices > Invoice paid に設定します。必要に応じて、Invoice expired にも設定できます。URL は次のような形式です: https://your-site/wc-api/xendit_p_callback/。設定画面に表示されたとおりに正確にコピーしてください。

Invoice paid: 購入者が請求書を支払いました。後述の確認の後、注文は支払い済みになります。

Invoice expired: 請求書は支払われないまま期限切れになりました。注文がまだこの請求書を待っていた場合、注文は失敗になります。

次に、各モードの Webhook verification token を Xendit Dashboard から対応するフィールドにコピーします。Xendit は x-callback-token ヘッダーでこれを送信します。請求書が作成されたモードのトークンを含まない通知は拒否されます。トークンが証明するのは、通知が Xendit から届いたことだけです。請求書のステータス、金額、通貨は、必ずそのモードのシークレットキーを使って Xendit API から再取得されます。ウェブフックがない場合、注文は、購入者が支払い後にストアに戻ったときにのみ確定します。

Test Webhook Verification Token: Xendit テストモードのウェブフック検証トークン。

Live Webhook Verification Token: Xendit 本番モードのウェブフック検証トークン。

支払い

Invoice Description: Xendit の請求書に表示される説明。プレースホルダー {order_id}、{order_number}、{site_name} を使用できます。HTML は削除され、テキストは 255 文字で切り捨てられます。デフォルト: Order #{order_id}。

Order Status After Payment: Xendit が支払いを確認した後に設定される注文ステータス。ステータスは 1 回のステータス変更で即座に設定されます。

Processing: WooCommerce のデフォルト（デフォルト）。ダウンロード可能な仮想商品だけの注文は、完了になります。

Completed: 支払い済みのすべての注文が完了になります。

詳細設定

Debug Log: Log API requests and webhooks は、リクエスト、ウェブフック、ステータス変更を WooCommerce > Status > Logs に書き込みます。ソースは wcp_xendit_payment_gateway です。この設定がオフでも、エラーと警告は常に記録されます。APIキー、トークン、購入者データは記録されません。デフォルト: オフ。

Delete Data on Uninstall: Delete the plugin settings and logs when the plugin is deleted。プラグインを無効化しても、何も削除されません。注文データ（注文内の請求書 ID）は常に保持されます。デフォルト: オフ。

チェックアウト

決済方法は、ストア通貨が IDR、PHP、VND、THB、MYR、USD、SGD のいずれかの場合に表示されます。Pay for order ページでは、注文通貨が基準になります。購入者は決済方法（デフォルトは Xendit）を選んで注文します。プラグインは注文通貨で注文合計額の Xendit 請求書を作成し、購入者を Xendit の請求書ページに送ります。IDR と VND の金額は、Xendit がこれらの通貨で小数点を受け付けないため、整数に丸められます。購入者の請求先メールアドレスは Xendit に渡されます。請求書ページで購入者は、この通貨について Xendit アカウントで有効になっている決済チャネル（バーチャル口座、電子ウォレット、QR コード、店頭払い、カードなど）のいずれかで支払います。

支払い後、購入者はストアの注文受付ページに戻ります。注文が支払い済みになるのは、Xendit が確認した後だけです。ウェブフックによる確認か、購入者がそのページに到達したときにサーバーから Xendit API へのリクエストによる確認です。それまで、注文は支払い待ちのままです。

請求書が失敗したり期限切れになったりすると、Xendit は購入者を戻します。チェックアウトで行われた注文は、WooCommerce の標準的な方法でキャンセルされ、その請求書は期限切れになります。Pay for order ページから支払われた注文（たとえば、購入者のために作成した注文）は、The Xendit payment was not completed. You can try again or choose another payment method. というメッセージとともに支払いページに戻り、引き続き支払い可能です。

購入者は、未払いの注文を再び支払うことができます。注文合計額、通貨、モードが変わらず、未決済の請求書がまだ有効であれば、購入者は同じ請求書に送られます。そうでない場合、古い請求書が先に期限切れになり、新しい請求書が作成されます。そのため、1 つの注文に未決済の請求書が 2 つ存在することはありません。古い請求書がすでに支払い済みの場合は、新たに支払いを求める代わりに、注文が完了になります。

Xendit が支払いを開始できない場合、購入者には短いメッセージが表示され、別の決済方法を選択できます。例えば、Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method.、アカウントでその通貨が受け付けられていないこと、または注文合計額が Xendit の金額制限を超えていることを伝えるメッセージです。技術的な理由はログに書き込まれます。合計額がゼロの注文は、Xendit では支払えません。

決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。テストモードでは、チェックアウトブロックに決済方法の下に Test mode: no real money is charged. と表示されます。WooCommerce High-Performance Order Storage（HPOS）に対応しています。

支払いは常に Xendit のページで行われます。プラグインには、WooCommerce からの返金、保存済みカード、サブスクリプションや定期払い、チェックアウトページのカードまたは電子ウォレットの入力欄、オーソリとキャプチャの個別処理、xenPlatform のサブアカウント、カスタムの請求書有効期限、決済手数料はありません。

注文

注文ステータス

Pending payment: 請求書は作成されましたが、購入者がまだ支払っていないか、Xendit がまだ支払いを確認していません。注文メモには、請求書 ID、金額、通貨、モードが表示されます。

Processing or Completed: 支払いが確認されました。ステータスは Order Status After Payment に従います。注文メモには、請求書 ID、支払われた金額、決済チャネル、モードが表示されます。トランザクション ID は Xendit の請求書 ID です。

On hold: 支払い済みの請求書が注文合計額または通貨と一致しなかったか、合計額より少ない金額しか支払われませんでした（たとえば、請求書を作成した後に注文が編集された場合）。注文メモにその理由が説明されます。注文がすでに保留になっていた場合も同様です。Xendit Dashboard で支払いを確認してから、注文を処理するか、支払いを返金してください。

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

Cancelled: 購入者が失敗または期限切れの請求書から戻ったか、注文があなたまたは未払い注文に対する WooCommerce のタイムアウトによってキャンセルされました。未決済の請求書は期限切れになるため、もう支払うことはできません。Xendit がこれを受け付けない場合、メモで Xendit Dashboard から請求書を期限切れにするよう求められます。

すでに支払い済み、キャンセル済み、または返金済みの注文に対して請求書が支払われた場合、注文は変更されません。メモで、Xendit Dashboard で支払いを返金するか、注文を手動で復元するよう求められます。

返金

返金は WooCommerce から Xendit に送信されません。Xendit Dashboard で支払いを返金し（注文メモとトランザクション ID に請求書 ID が含まれています）、WooCommerce では返金を手動で記録してください。

ライセンスキー

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

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

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

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

トラブルシューティング

チェックアウトに Xendit が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、有効なモードに正しいプレフィックスのシークレットキーがあること（テストモードでは xnd_development_ の Test Secret Key、本番モードでは xnd_production_ の Live Secret Key）、そしてストア通貨が IDR、PHP、VND、THB、MYR、USD、SGD のいずれかであることを確認してください。キーがないか間違っている場合、設定のバナーに警告が表示されます。

支払いは完了したのに、注文が支払い待ちのまま: ウェブフックが機能していません。使用しているモード（テストまたは本番）の Xendit Dashboard で、設定に表示された URL が Invoice paid に設定されていること、そして、そのモードの検証トークンが対応するフィールドに保存されていることを確認してください。Xendit Dashboard には、ウェブフックごとにストアからの応答が表示されます。購入者が注文受付ページに戻ると、注文も確認されます。

ウェブフックの応答「Webhook verification token is not configured」: 2 つの検証トークンのどちらも設定されていません。トークンを設定に貼り付けてください。

ウェブフックの応答「Unauthorized」: Xendit から送られたトークンが、設定内のどのトークンとも一致しません。正しいモードのトークンを再度コピーしてください。

ウェブフックの応答「Token does not match the mode of this invoice」: 請求書は別のモードで作成されました。テスト通知が本番の注文を確認することはなく、その逆もありません。支払いが行われたモードで、ウェブフックとトークンを設定してください。

ウェブフックの応答「Ignored: not an invoice of this store」: この請求書は、このストアでは作成されていません。たとえば、同じ Xendit アカウント上の別の連携によって作成された場合です。Xendit Dashboard の Test ボタンでもこの応答が返されます。これは、URL とトークンが機能していることを確認するものです。

ウェブフックの応答「Temporary error」: 請求書を確認するために Xendit API に接続できなかった、請求書のモードのシークレットキーがない、または同時に別のリクエストで注文が更新されていた、のいずれかです。Xendit はウェブフックを再試行します。両方のモードの注文がある場合は、両方のシークレットキーが設定されているか確認してください。

キーが保存されない: 値がそのフィールドのプレフィックスで始まっていません。テストキーは xnd_development_、本番キーは xnd_production_ で始まります。

購入者に「This payment method is temporarily unavailable」と表示される: Xendit がリクエストを拒否しました。たとえば、シークレットキーが間違っている、または Money-in（請求書）への書き込み権限がないなどの理由です。必要に応じて Debug Log をオンにし、WooCommerce > Status > Logs（ソース: wcp_xendit_payment_gateway）を確認してください。請求情報に関するメッセージは、Xendit がリクエストデータ（たとえばメールアドレス）を受け付けなかったことを意味します。

購入者に「A payment for this order was already received by Xendit and is being reviewed」と表示される: この注文の以前の請求書が支払われましたが、注文と一致しなかったため、注文は保留になっています。Xendit Dashboard で支払いを確認してください。

支払い後に注文が On hold になる: 注文メモを確認してください。支払われた金額または通貨が注文と異なっていました。注文を処理するか、Xendit Dashboard で支払いを返金してください。

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

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページでプラグインを無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定、プラグインのその他のオプション、一時データ、およびログ（ローテーションされたログファイル、データベースのログエントリ、バージョン 1.0 のログフォルダーを含む）は、Delete Data on Uninstall がオンになっている場合にのみ削除されます。それ以外の場合は、後で再インストールするために残ります。既存の注文は、支払いメモ、請求書 ID、トランザクション ID を保持します。

Xendit は、それぞれの所有者の商標です。本プラグインは Xendit と提携しておらず、Xendit による推奨も受けていません。