VibeFox Xendit for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古いバージョンの PHP ではモジュールをインストールできません。

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

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

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox Xendit Payment Gateway を探して Configure をクリックすることもできます。

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

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

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

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上のボックスには現在のモードが表示されます。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: テスト用シークレットキーで請求書を作成するため、実際の料金は請求されません。初期値：オン。本番用シークレットキーで実際の支払いを受け付けるには、オフにします。オンの間は、決済方法の下に Test mode: no real money is charged. と表示されます。

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

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

保存済みのキーとトークンは再表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

ウェブフック

ウェブフックは、請求書が支払われたことをショップに通知します。Xendit Dashboard > Settings > Developers > Webhooks で、このセクションの Webhook URL に表示された URL を、テストモードと本番モードの両方で Invoices > Invoice paid に設定します。必要に応じて Invoice expired にも設定できます。フレンドリー URL を有効にしている場合は、https://your-shop/module/wcp_xendit_payment_gateway/webhook のような形式になります。先頭に /en/ などの言語コードが付くこともあります。設定に表示されたとおりに正確にコピーしてください。

Invoice paid: 購入者が請求書を支払いました。注文は、下記の確認の後に作成されます。

Invoice expired: 請求書が支払われないまま期限切れになりました。支払いの試行は終了し、カートは再度支払いできます。

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

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

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

Clear saved secrets: キーまたはトークンにチェックを入れて Save をクリックすると、削除されます。空のフィールドでは保存済みの値が保持されます。

支払い

Invoice Description: Xendit の請求書に表示される説明文です。プレースホルダー {order_id}、{order_number}、{site_name} を使用できます。注文は支払い後に作成されるため、{order_id} と {order_number} はカート番号になります。HTML は削除され、テキストは 255 文字に切り詰められます。初期値：Order #{order_id}。

Order Status After Payment: Xendit が支払いを確認した後に設定される注文ステータスです。

Processing (default): 注文に Payment accepted が設定されます。これは支払い済み注文に対する PrestaShop の標準ステータスです。

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

詳細設定

Debug Log: API リクエストとウェブフックを、モジュールフォルダ内の logs/xendit_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。このオプションがオフでも、エラーと警告は常に記録されます。API キー、トークン、購入者データは記録されません。初期値：オフ。

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

Delete Data on Uninstall: オンにすると、モジュールのアンインストール時にモジュールの設定とログが削除されます。注文データ（注文の請求書 ID）と Xendit payment on hold 注文ステータスは、常に保持されます。初期値：オフ。

チェックアウト

カート通貨が IDR、PHP、VND、THB、MYR、USD、SGD のいずれかの場合に、決済方法が表示されます。購入者は支払いステップでそれを選択し（初期値は Xendit）、確定します。モジュールはカート合計をカート通貨で請求する Xendit 請求書を作成し、購入者を Xendit の請求書ページに送ります。Xendit はこれらの通貨の小数を受け付けないため、IDR と VND の金額は整数に丸められます。購入者のメールアドレスは Xendit に渡されます。請求書ページで購入者は、Xendit アカウントでこの通貨に対して有効になっている決済チャネル（バーチャル口座、電子ウォレット、QR コード、店頭払い、カードなど）のいずれかで支払います。この時点では、まだ注文は存在しません。

支払い後、購入者はショップに戻ります。注文は、Xendit が確認した後にのみ支払い済みとしてマークされます。ウェブフック経由、または購入者が戻ったときにサーバー側から Xendit API へ問い合わせることで確認されます。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。Xendit がまだ支払いを確認していない場合は、Payment confirmation ページに Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. というメッセージと、Check again および Back to checkout のボタンが表示されます。ウェブフックが届くと、すぐに注文が作成されます。

請求書が失敗したり期限切れになったりすると、Xendit は購入者をショップに戻します。モジュールは最初に請求書を確認し（別のタブで支払われている可能性があるため）、その後、もう支払えないように期限切れにします。購入者はチェックアウトに戻り、The Xendit payment was not completed. You can try again or choose another payment method. と表示されます。カートは保持されます。

購入者は同じカートを再度支払うことができます。カート合計、通貨、モードが変わっておらず、未決済の請求書がさらに 5 分以上有効であれば、購入者は同じ請求書に案内されます。そうでなければ、古い請求書が先に期限切れにされ、新しい請求書が作成されます。そのため、同じカートに未決済の請求書が 2 件同時に存在することはありません。古い請求書がすでに支払われていた場合は、新たに支払いを求める代わりに注文が作成されます。

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

ウェブフックは、ショップがメンテナンスモードの間も機能し、ショップの国別制限によってブロックされることはありません。

支払いは常に Xendit のページで行われます。モジュールには、バックオフィスからの返金、保存済みカード、サブスクリプションや定期支払い、チェックアウトページ上のカードや電子ウォレットのフィールド、オーソリとキャプチャの個別処理、xenPlatform のサブアカウントはありません。

注文

注文ステータス

まだ注文はありません: 購入者は Xendit に移動しましたが、まだ支払っていないか、Xendit がまだ支払いを確認していません。存在するのはカートだけです。

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

Xendit payment on hold: 支払い済みの請求書がカート合計または通貨と一致しなかったか、合計より少ない金額が支払われました（例えば、請求書の作成後にカートが変更された場合）。メモに理由が記載されます。Xendit Dashboard で支払いを確認してから、注文を処理するか、支払いを返金してください。同じカートの別の請求書が後で正しい金額で支払われた場合、支払いが記録され、注文は支払い済みのステータスに移ります。

キャンセル済みまたは返金済みの注文に対して請求書が支払われた場合、注文ステータスは変更されません。メモで、Xendit Dashboard で支払いを返金するか、注文を手動で復元するよう案内されます。すでに支払い済みの注文に対して 2 件目の請求書が支払われた場合、注文は変更されず、メモで、Xendit Dashboard で重複した支払いを返金するよう案内されます。

Xendit payment ブロック

注文ページには Xendit payment ブロックが表示されます。請求書 ID、モード（テスト支払いには Test mode バッジ付き）、支払いステータス、注文のすべての請求書の一覧（日付、請求書、外部 ID、金額と支払い済み金額、ステータス、決済チャネル）、そして注文の Payment notes が含まれます。

返金

返金はショップから Xendit に送信されません。Xendit Dashboard で支払いを返金し（Xendit payment ブロックに表示された請求書 ID で検索します）、注文に返金を手動で記録してください。注文ページにある PrestaShop の標準の返金ボタンは、Xendit を通じて返金を行いません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Xendit が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、有効なモードに正しいプレフィックスのシークレットキーがあること（テストモードでは xnd_development_ で始まる Test Secret Key、本番モードでは xnd_production_ で始まる Live Secret Key）、そしてカート通貨が IDR、PHP、VND、THB、MYR、USD、SGD のいずれかであることを確認してください。キーが見つからない場合や誤っている場合、設定ページに警告が表示されます。Payment > Preferences で、カート通貨、購入者の国、購入者のグループに対してモジュールが許可されているかも確認してください。

支払いは完了したが、注文が作成されなかった: ウェブフックが機能していません。使用しているモード（テストまたは本番）の Xendit Dashboard で、Webhook URL に表示された URL が Invoice paid に設定されていること、およびそのモードの検証トークンが対応するフィールドに保存されていることを確認してください。Xendit Dashboard には、ウェブフックごとにショップの応答が表示されます。注文は、購入者が支払い後にショップに戻ったときにも作成されます。

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

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

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

ウェブフックの応答 Ignored: not an invoice of this store: 請求書はこのショップで作成されたものではありません。例えば、同じ Xendit アカウントの別の連携によって作成されたものです。Xendit Dashboard の Test ボタンでもこの応答が返され、URL とトークンが機能していることが確認できます。Ignored: unknown order と Ignored: unknown invoice は、カートまたは請求書がこのショップで認識されていないことを意味します。

ウェブフックの応答 Temporary error: 請求書を確認するための Xendit API に接続できなかった、請求書のモードのシークレットキーがない、カートが別のリクエストによって同時に更新されていた、または注文を作成できなかった（例えばモジュールが無効になっている）ことを意味します。Xendit はウェブフックを再試行します。両方のモードで支払いを開始した場合は、両方のシークレットキーが設定されていることを確認し、Debug Log をオンにして理由を確認してください。

ブラウザでウェブフックの URL に Method not allowed と表示される: これは正常です。この URL は Xendit からのリクエストのみを受け付けます。

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

購入者に This payment method is temporarily unavailable と表示される: Xendit がリクエストを拒否しました。例えばシークレットキーが誤っている、または Money-in（請求書）の書き込み権限がない場合です。モジュールのページにある Log フィールドを確認してください。請求先情報に関するメッセージは、Xendit がリクエストのデータ（例えばメールアドレス）を受け付けなかったことを意味します。

購入者に A payment for this order was already received by Xendit and is being reviewed と表示される: このカートの以前の請求書が支払われましたが、注文はまだ確認できていません。Xendit Dashboard とログで支払いを確認してください。

購入者に We could not match this payment to an order と表示される: Xendit からの戻りリンクがこのショップのカートに属していないか、カートのどの請求書とも照合できませんでした。Xendit Dashboard とログで支払いを確認してください。

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

開発者向けに、このモジュールは請求書リクエスト、通貨の一覧、通貨ごとの小数桁数を変更するためのフック actionWcpXenditInvoiceRequest、actionWcpXenditSupportedCurrencies、actionWcpXenditCurrencyDecimals を提供します。

アンインストール

Modules > Module Manager に移動し、VibeFox Xendit Payment Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete Data on Uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。注文の Xendit 請求書データと Xendit payment on hold 注文ステータスは、常に保持されます。既存の注文は、支払いメモとトランザクション ID を保持します。

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