VibeFox Xendit for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。

PHP: 8.0 以降。

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

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

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

インストール

ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで展開してください。README.txt、OpenCart 3 用のパッケージ wcp_xendit_payment_gateway-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ wcp_xendit_payment_gateway.ocmod.zip が含まれています。お使いの OpenCart のバージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer を開き、Upload をクリックして、ファイル wcp_xendit_payment_gateway-oc3-(version).ocmod.zip を選択します。本拡張機能には OCMOD の変更がないため、Extensions > Modifications を更新する必要はありません。インストーラーを使わず、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions を開き、種類 Payments を選びます。VibeFox Xendit Payment Gateway を見つけて、Install（緑色の + ボタン）をクリックします。管理者ユーザーに、決済拡張機能の一覧を変更する権限が必要です。

3. Edit（鉛筆ボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key フィールドに VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。

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

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

OpenCart 4

1. 管理画面で Extensions > Installer を開き、Upload をクリックして、ファイル wcp_xendit_payment_gateway.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。

2. パッケージは、同じページのインストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions を開き、種類 Payments を選びます。VibeFox Xendit Payment Gateway を見つけて、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆ボタン）をクリックします。

4. OpenCart 3 の手順 3 から 5 と同じように、ライセンスキー、Xendit のキー、Webhook を入力します。設定ページとそのフィールドは両方のバージョンで同じです。Webhook URL のみが異なります（Webhook を参照）。

新規インストール時は、支払い方法がオフ、テストモードがオンの状態になります。

設定

すべての設定は拡張機能のページにあります: Extensions > Extensions > Payments > VibeFox Xendit Payment Gateway > Edit。セクションは左側に一覧表示されます。一覧の下にある Save ボタンでページ全体を保存します。拡張機能を変更する権限がない場合、ページには設定は表示されますが、保存はできません。

設定の上にあるボックスには、現在有効なモードが表示されます。TEST MODE（請求書はテストのシークレットキーで作成され、実際の料金は請求されません）または LIVE MODE（請求書は本番のシークレットキーで作成され、顧客に請求されます）のいずれかです。有効なモードのシークレットキーがない場合、またはプレフィックスが違う場合、ページが警告します（その場合、チェックアウトで支払い方法は表示されません）。また、有効なモードの Webhook 検証トークンが空の場合も警告します（Xendit からの通知は拒否されるため、注文は顧客がストアに戻ったときにしか更新されません）。

保存時、Title は空欄にできず（最大 128 文字）、Sort Order は整数である必要があります（負の数も可）。Total は 0 以上の数値である必要があり、ジオゾーンと注文ステータスは存在している必要があります。そうでない場合は何も保存されず、ページに該当する項目が表示されます。

Xendit

Enable/Disable: Enable Xendit で支払い方法のオン／オフを切り替えます。デフォルト: off。

Title: 顧客がチェックアウトで見る支払い方法の名前です。注文にも、この名前が支払い方法として保存されます。デフォルト: Xendit。必須、最大 128 文字。

Description: Confirm Order の手順で、確認ボタンの上に顧客へ表示される文章です。デフォルト: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

Sort Order: チェックアウトの支払い方法の中での Xendit の表示順です。空欄のままにするか、整数を入力します。

Geo Zone: 選択したジオゾーン内の支払い先住所に対してのみ Xendit を提供します。デフォルト: All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。

Total: Xendit を提供するために、注文がストアの既定の通貨で到達している必要があるチェックアウト合計金額です。空欄にすると、どの金額でも 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: テストのシークレットキーで請求書を作成するため、実際の料金は請求されません。デフォルト: on。オフにすると、本番のシークレットキーで実際の支払いを受け付けます。オンの間、顧客には Confirm Order の手順で 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. と表示されます。変更する場合にのみ新しい値を入力してください。保存済みの値を削除するには、フィールドの下にある Clear the saved value にチェックを入れて Save をクリックします。

Webhook

Webhook は、請求書が支払われたことをストアに通知します。Xendit Dashboard > Settings > Developers > Webhooks（このセクションにリンクがあります）で、Webhook URL に表示された URL を、テストモードと本番モードの両方について Invoices > Invoice paid に設定します。必要に応じて Invoice expired にも設定できます。OpenCart 3 では URL は https://your-store/index.php?route=extension/payment/wcp_xendit_payment_gateway/webhook のような形式、OpenCart 4 では https://your-store/index.php?route=extension/wcp_xendit_payment_gateway/payment/wcp_xendit_payment_gateway.webhook のような形式です。URL は OpenCart をインストールしたストアのフロントエンドのアドレスから作られます。設定に表示されたとおりに正確にコピーしてください。インターネットから到達可能である必要があります。

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

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

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

支払い

Invoice Description: Xendit の請求書に表示される説明です。プレースホルダーの {order_id} と {order_number}（どちらも OpenCart の注文番号）と {site_name}（ストア名）を使用できます。HTML は削除され、テキストは 255 文字に切り詰められます。デフォルト: Order #{order_id}。

Order Status After Payment: 確定した支払いが、1 回のステータス変更で設定する注文ステータスです。

OpenCart は Confirm Order の手順で、ステータスなし（注文の欠落）として注文を作成します。注文にステータスが付くのは、Xendit が API を通じて支払いを確認した後だけです。以下の各フィールドには、お使いの OpenCart の注文ステータスが一覧表示されます。

Paid Order Status: Processing で確定した支払いの後のステータスです。デフォルト: Processing。

Complete Order Status: Completed で確定した支払いの後のステータスです。デフォルト: Complete。

On Hold (Review) Status: 注文と異なる金額または通貨で請求書が支払われた場合（請求書の作成後にカートが変更された、または一部のみの支払い）に使われます。メモに理由が記録されます。デフォルト: Pending。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

詳細設定

Debug Log: API リクエストと Webhook を、OpenCart のログフォルダ（storage/logs）にある xendit_p_debug.log.php に書き込みます。このファイルは Web から開くことができず、5 MB に達すると xendit_p_debug.old.log.php に移動されます。エラーと警告は、この設定がオフでも常に記録されます。API キー、トークン、顧客データは記録されません。デフォルト: off。

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

Delete Data on Uninstall: オンにすると、拡張機能のアンインストール時にゲートウェイの設定とログが削除されます。注文データ（注文の Xendit 請求書 ID）は常に保持されます。デフォルト: off。

インポート / エクスポート

Export: Download JSON で、設定を JSON ファイルとして保存します。シークレットキーとトークンはエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定を復元します。保存済みのシークレットキーとトークンは保持されます。

チェックアウト

チェックアウトの通貨が IDR、PHP、VND、THB、MYR、USD、SGD のいずれかである場合に、支払い方法が表示されます。顧客は Payment Method の手順でこれを選択します（デフォルトは Xendit）。Confirm Order の手順で、顧客にはあなたの説明文が表示されます。OpenCart はこの手順で注文を作成しますが、まだステータスはありません。顧客が Confirm Order をクリックすると、拡張機能は注文合計金額（注文通貨）に対して Xendit の請求書を作成し、顧客を Xendit の請求書ページに移動させます。IDR と VND の金額は、Xendit がこれらの通貨の小数を受け付けないため、整数に丸められます。顧客のメールアドレスは Xendit に渡されます。請求書ページで顧客は、Xendit アカウントでこの通貨に対して有効になっている支払いチャネル（バーチャル口座、電子ウォレット、QR コード、小売店舗、カードなど）のいずれかで支払います。OpenCart 4 では、購入者は決済方法ブロックの Choose ボタンから、Payment method options のウィンドウで決済方法を選択し、チェックアウトページの下部で Confirm Order をクリックします。

支払い後、顧客はストアに戻ります。注文が支払い済みとしてマークされるのは、Xendit が確認した後だけです。Webhook によって確認されるか、顧客が戻ったときに Xendit API へサーバー側のリクエストを送って確認されます。その後、注文は通常の OpenCart の方法でステータスを受け取り、通常の注文メールと在庫の更新が行われ、顧客には OpenCart の注文成功ページが表示されます。Xendit がまだ支払いを確認していない場合、Payment confirmation ページに Your payment has not been confirmed by Xendit yet. Your order will be confirmed as soon as Xendit confirms it — please do not pay again. と表示され、Check again と Back to checkout のボタンが表示されます。Webhook は届き次第、注文ステータスを設定します。

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

OpenCart 3 は Confirm Order の手順が表示されるたびに新しい注文を作成します。OpenCart 4 は、チェックアウトの注文を 1 つ保持して更新するため、請求書が失敗または期限切れになった後、次の Confirm Order は同じ注文に対して新しい請求書を作成します。同じカートの別の注文がすでに支払い済みの場合、顧客は直接成功ページに進み、二重に請求されることはありません。注文の合計金額、通貨、モードが変わらず、この注文の未払いの請求書があと 5 分以上有効な場合、顧客は同じ請求書に送られます。そうでない場合は、古い請求書を先に期限切れにしてから新しい請求書を作成するため、同じカートに未払いの請求書が 2 件存在することはありません。古い請求書がすでに支払われている場合は、新しい支払いを作るのではなく、その支払いが確認されます。

OpenCart 4 では、チェックアウトの注文がストアによってその間に閉じられた場合（たとえばキャンセルまたは返金された場合）、またはすでに支払い済みでも、その後カートが変更された場合（数量の変更を含む）、購入者は Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order. と表示されてチェックアウトに戻され、次の Confirm Order で新しい注文が支払われます。OpenCart 4 では、このメッセージ、支払いが完了しなかったことのメッセージ、および We could not match this payment to an order. If you were charged, please contact us. が、チェックアウトページの上部に表示されます。

Xendit が支払いを開始できない場合、顧客はボタンの上に短いメッセージが表示された Confirm Order の手順にとどまります。例えば Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method.、アカウントでその通貨が受け付けられないというメッセージ、または注文合計が Xendit の金額の上限・下限の範囲外であるというメッセージです。技術的な理由はログに書き込まれます。合計金額がゼロの注文は、Xendit では支払えません。

Webhook と顧客の戻りも、ストアがメンテナンスモードの間に機能します。OpenCart 3 は支払い拡張機能のリクエストを通過させ、OpenCart 4 では拡張機能がそのためのスタートアップアクションを追加します。

支払いは常に Xendit のページで行われます。本拡張機能には、管理画面からの返金、保存済みカード、定期購入や継続払い、チェックアウトページのカードや電子ウォレットの入力欄、与信と売上確定の分離、xenPlatform のサブアカウントはありません。

注文

注文ステータス

ステータスなし（注文の欠落）:顧客は Xendit に送られ、まだ支払っていないか、Xendit がまだ支払いを確認していません。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。

Paid Order Status または Complete Order Status（デフォルトは Processing または Complete）:支払いが確認されました。ステータスは Order Status After Payment に従います。メモには、請求書 ID、支払われた金額、支払いチャネル、モードが表示されます。

On Hold (Review) Status（デフォルトは Pending）:支払い済みの請求書が注文合計や通貨と一致しなかった、または合計より少ない金額が支払われました（例えば、請求書の作成後にカートが変更された場合）。メモにその理由が説明されます。Xendit Dashboard で支払いを確認してから、注文を処理するか、支払いを返金してください。同じ注文の別の請求書が後で正しい金額で支払われた場合、注文は支払い済みのステータスに移ります。

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

メモは注文の History に記録されるエントリで、顧客には表示されません。メモはすべて Xendit という語で始まります。

VibeFox Xendit Payment Gateway タブ

Sales > Orders で Xendit により支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox Xendit Payment Gateway タブには、Xendit invoice、Mode（テスト支払いには Test のラベル付き）、支払いの Status、Invoices of this order and its cart の表（日付、注文、請求書 ID、外部 ID、モード、金額、支払済み金額、ステータス、支払いチャネル）、注文の Payment notes が表示されます。このタブは、拡張機能にアクセスできるユーザーに表示されます。

返金

返金はストアから Xendit に送信されません。Xendit Dashboard で支払いを返金し（タブに表示された請求書 ID を検索します）、その後で OpenCart の注文ステータスを変更してください。Sales > Returns での商品返品は、Xendit を通じて金額を返金しません。

ライセンスキー

本拡張機能は、vibefox.net で発行された VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Xendit Payment Gateway は、Extensions > Extensions > Payments > VibeFox Xendit Payment Gateway > Edit ページで設定の上にある最初のブロックです。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーがマスクされて表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ボタン Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）が表示されます。その下には Product: opencart-payment-xendit の行と、vibefox.net アカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、この拡張機能に対する Modify 権限を持つ管理者ユーザーだけです。ブロックの文言は管理画面の言語に従います（英語とロシア語が含まれます）。

キーが受け付けられない場合、ブロックにその理由が表示されます。例えば Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on です。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後に Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認したステータスで動作を続けます。

1 つのキーは 1 つのドメインで動作します。ドメインは OpenCart の設定にあるストアのアドレスです。ストアからキーを削除してもドメイン枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウトで顧客に Xendit は表示されません。支払いが開始された場合、顧客には This payment method is not available. Please choose another one. と表示されます。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアで支払い方法が (unlicensed — visible to admins only) の印付きで引き続き表示されるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面のログインを認識しないため、有効なキーがない場合、支払い方法は全員に対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。すでに開始された支払いは引き続き確認されます。

ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーを入力してから最初の 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 のいずれかであることを確認してください。キーがない、または間違っている場合、設定ページに警告が表示されます。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に到達していることも確認してください。

支払いは完了したが、注文にステータスが付かない:Webhook が機能していません。使用しているモード（テストまたは本番）の Xendit Dashboard で、Webhook URL に表示された URL が Invoice paid に設定されていること、そのモードの検証トークンが対応するフィールドに保存されていることを確認してください。Xendit Dashboard には、各 Webhook に対するストアの応答が表示されます。顧客が支払い後にストアに戻った場合も、注文にはステータスが付きます。

Webhook answers Webhook verification token is not configured:どちらの検証トークンも設定されていません。トークンを設定に貼り付けてください。

Webhook answers Unauthorized:Xendit から送られたトークンが、設定のどのトークンとも一致しません。正しいモードのトークンを再度コピーしてください。

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

Webhook answers Ignored: not an invoice of this store:請求書はこのストアで作成されたものではありません。例えば、同じ Xendit アカウントの別の連携によって作成されたものです。Xendit Dashboard の Test ボタンも同じ応答を受け取ります。これは URL とトークンが機能していることを示します。Ignored: unknown order と Ignored: unknown invoice は、その注文または請求書がこのストアに認識されていないことを意味します。

Webhook answers Temporary error:請求書を確認するために Xendit API に接続できなかった、請求書のモードのシークレットキーがない、または別のリクエストによって同時にカートが更新されていました。Xendit は Webhook を再送します。両方のモードで支払いを開始した場合は両方のシークレットキーが設定されているか確認し、理由を確認するために Debug Log をオンにしてください。

Webhook 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 とログで支払いを確認してください。

支払い後に注文が確認ステータスになる:VibeFox Xendit Payment Gateway タブのメモを読んでください。支払われた金額または通貨が注文と異なっていました。注文を処理するか、Xendit Dashboard で支払いを返金してください。

開発者向け: 拡張機能は、請求書リクエスト、通貨の一覧、通貨ごとの小数桁数を変更するために、OpenCart のイベント xendit_p_invoice_request、xendit_p_supported_currencies、xendit_p_currency_decimals を発行します。

アンインストール

Extensions > Extensions を開き、種類 Payments を選んで、VibeFox Xendit Payment Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは必ず削除されます。OpenCart は拡張機能自身の設定を必ず削除します。Enable/Disable、Sort Order、Geo Zone、Total、そして Payment セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。OpenCart 4 では、拡張機能のイベントと、メンテナンスモードで Webhook と顧客の戻りを通過させるスタートアップアクションも削除されます。Delete Data on Uninstall がオンの場合、その他のゲートウェイ設定（タイトル、説明、テストモード、キー、トークン、請求書の説明、支払い後の注文ステータス、ログ設定）とログも削除されます。オフの場合は、後で再インストールするために保持されます。注文の Xendit 請求書データは常に保持されます。既存の注文は支払いメモを保持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer を開き、インストール済み拡張機能の一覧にある VibeFox Xendit Payment Gateway の横の Uninstall（オレンジ色の − ボタン）をクリックして、次にアップロードしたパッケージを削除するため Delete（赤いごみ箱ボタン）をクリックします。

Xendit は各所有者の商標です。本拡張機能は Xendit と提携しておらず、Xendit による推奨も受けていません。