VibeFox KOMOJU for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 7.0 以降、インストール済みで有効であること。なければプラグインは有効化できません。

PHP: 8.0 以降。

HTTPS: サイトに HTTPS が必要です。KOMOJU がウェブフック URL にアクセスできる必要があります。

KOMOJU account: 秘密キー（sk_live_...、テストモードでは sk_test_...）と、KOMOJU ダッシュボードで作成したウェブフックのシークレットトークンが必要です（「設定」参照）。公開可能キーは不要です。

Store currency: JPY、USD、EUR、TWD、KRW、PLN、GBP、HKD、SGD、NZD、AUD、IDR、MYR、PHP、THB、CNY、BRL、CHF、CAD、VND。その他の通貨では決済方法を非表示にします。

VibeFox license key: vibefox.net で購入します。1 キーは 1 ドメインで使用できます。

インストール

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

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

3. 設定を開きます：WooCommerce > Settings > Payments > KOMOJU Payment > Manage。またはプラグイン一覧で名前の下の Settings をクリックします。

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

5. KOMOJU ダッシュボードで、設定ページの URL と記載されたイベントでウェブフックを追加し、シークレットトークンをコピーします（「設定」参照）。

6. 本番の秘密キーとウェブフックのシークレットトークン、およびサンドボックス用のテスト値を入力します。Enable/Disable を有効にして保存します。

設定

すべての設定は WooCommerce > Settings > Payments > KOMOJU Payment にあります。テストモード中はフィールド上部に KOMOJU Sandbox Mode is enabled. を表示します。現在のモードに秘密キーがない場合（チェックアウトで決済方法を非表示）、ウェブフックのシークレットトークンがない場合（KOMOJU 通知を拒否するため、コンビニ払いと銀行振込は確定しません）、ストア通貨が未対応の場合に警告します。決済方法一覧では、現在のモードに秘密キーを設定するまで KOMOJU は要設定と表示され、サンドボックス中はテストモードのバッジが付きます。

一般

Enable/Disable: Enable KOMOJU Payment Gateway で決済方法を有効・無効にします。既定値：off。

Title: 購入者がチェックアウトで見る決済方法名。既定値：KOMOJU Payment。

Description: チェックアウトで決済方法の下に表示する文章。既定値：Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

本番 API キー

KOMOJU ダッシュボードで確認します。秘密キーは Settings > API keys、ウェブフックのシークレットトークンは Settings > Webhooks にあります（先に下記のウェブフック URL を追加してください）。

Live Secret Key: KOMOJU 本番秘密キー。sk_live_ で始まります。

Live Webhook Secret Token: 本番ウェブフックのシークレットトークン。各通知の署名を検証します。

テストモード

KOMOJU はテストと本番で同じ API アドレスを使い、キーがモードを決めます。注文は支払い時のモードを保持するため、返金と状態確認には常にそのモードのキーを使います。

Sandbox Mode: Enable test mode (use the test keys below, no real payments)。既定値：off。有効中はチェックアウトの説明の上に Test mode を表示します。

Sandbox Secret Key: KOMOJU テスト秘密キー。sk_test_ で始まります。

Sandbox Webhook Secret Token: テストモードのウェブフックのシークレットトークン。

ウェブフック URL

ウェブフックは、後払いのコンビニ払いや銀行振込を含む決済をストアに通知します。KOMOJU ダッシュボードの Settings > Webhooks で、この設定欄の URL を本番とテスト用に追加します。形式は https://your-site/wc-api/komoju_p_webhook/ です。サイトの URL に言語接頭辞がある場合も、設定に表示されたとおり正確にコピーしてください。その後、各ウェブフックのシークレットトークンを Live Webhook Secret Token または Sandbox Webhook Secret Token にコピーします。

次のイベントを選択します：

期限切れ、キャンセル、失敗のイベントは注文の現在の決済にのみ作用します。以前の試行の決済が、別の方法で支払い中の注文をキャンセルすることはありません。有効な署名がないウェブフックは拒否します。どちらのシークレットトークンで署名されたものも受け付けますが、同じモードの注文に限ります。ウェブフックがなくてもカード決済は購入者の帰還時に確定しますが、コンビニ払いと銀行振込は確定しません。

詳細設定

Invoice Prefix: KOMOJU に送る注文番号の接頭辞。同じ KOMOJU アカウントを複数ストアで使う場合、ストアごとに固有にします。既定値：WC-。

Enable Logging: Log KOMOJU events and API calls を WooCommerce > Status > Logs に記録します。ソースは wcp_komoju_payment。キーや購入者データは含みません。エラーは常に記録します。既定値：off。

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted。無効化では何も削除しません。注文データ（注文内の KOMOJU 決済 ID）は常に保持します。既定値：off。

チェックアウト

購入者が決済方法（既定は KOMOJU Payment）を選び注文します。プラグインは注文合計額と注文通貨で KOMOJU 決済セッションを作成し、購入者を KOMOJU 決済ページへ送ります。請求先メールアドレス、氏名、請求先・配送先住所、注文商品を KOMOJU に渡します。ページはサイト言語に応じて日本語、英語、韓国語で表示されます（その他は英語）。そこで購入者が方法を選びます。提供される方法は貴店の KOMOJU アカウントと注文通貨によります。

支払い後、購入者はストアへ戻ります。プラグインは注文モードのキーで KOMOJU API から決済セッションを取得します。署名付きウェブフック、または帰還時のセッション取得で KOMOJU が確認した後にのみ支払い済みにします。その時点で KOMOJU に接続できない場合、購入者は注文受付ページへ移動し、We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes. が表示されます。

コンビニ払いと銀行振込では購入者に払込票を発行します。注文は保留となり、購入者が支払い、KOMOJU がウェブフックを送ると完了します。払込票が期限切れになるとキャンセルします。

未完了の場合、購入者は Pay for order ページへ戻り、The payment was not completed. You can try again or choose another payment method. が表示されます。新しい試行は合計額が同じなら開いているセッションを再利用します。古い合計額のセッションは KOMOJU でキャンセルし、その間に支払われたセッションは注文を確定します。未払い注文が貴店、購入者、WooCommerce の在庫保持タイマーによってキャンセルされると、開いている KOMOJU セッションもキャンセルされ、支払えなくなります。

KOMOJU が決済を開始できない場合、購入者には理由付きの KOMOJU could not accept this payment:、KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us.、Payment error: Could not connect to KOMOJU. Please try again in a moment. などの短いメッセージが表示されます。詳細は注文メモとログに追加します。

クラシックチェックアウト、チェックアウトブロック、Pay for order ページに対応します。WooCommerce High-Performance Order Storage（HPOS）と互換性があります。

サイト内のカードフォーム、保存済みカード、定期購入はありません。決済方法は制限せず、KOMOJU ページで選択します。手動キャプチャ操作はありません。手動キャプチャ用に承認された決済は KOMOJU ダッシュボードでキャプチャする必要があり、それまでは注文が保留になります。

注文と返金

注文ステータス

Pending payment: 購入者は KOMOJU に移動し、まだ支払っていないか、KOMOJU が未確認です。

Processing or Completed: KOMOJU が決済を確認しました。WooCommerce が支払い済み注文の通常ステータスを設定します。注文メモには KOMOJU 決済 ID、方法、確認経路（ウェブフックまたは帰還）を記載します。取引 ID は KOMOJU 決済 ID で、注文画面から KOMOJU ダッシュボードの決済にリンクします。

On hold: コンビニ・銀行振込の払込票が発行され支払い待ち、またはダッシュボードでキャプチャ待ちです。金額や通貨が不一致の場合、キャンセル後にキャプチャされた場合も保留になります。理由は注文メモに記載します。注文を履行するか返金してください。

Failed: 決済失敗。購入者は再試行できます。

Cancelled: 払込票の期限切れ、または決済のキャンセル。

Refunded: WooCommerce または KOMOJU ダッシュボードで全額返金済み。

支払い済み注文で 2 件目の決済がキャプチャされても、注文は再変更しません。重複ならダッシュボードで返金するようメモで求めます。返金済み注文は再開しません。

返金

注文を開き Refund をクリックし、金額を入力して Refund via KOMOJU Payment をクリックします。全額・一部返金に対応します。支払い時モードのキーを使うため、その秘密キーの設定が必要です。まず KOMOJU の決済を確認し、返金可能残額を超える返金は拒否します。自動返金できない場合（コンビニ払いなどでは購入者の銀行情報が必要）、KOMOJU のエラーを表示して何も記録しません。その場合はダッシュボードで処理してください。KOMOJU 確認後にのみ返金完了となり、成功した返金は注文メモに追加します。

KOMOJU が別通貨に換算した決済（EUR 注文に対する JPY のコンビニ払いなど）は WooCommerce から全額返金のみ可能です。一部返金はダッシュボードで行ってください。

ダッシュボードでの返金はウェブフックで届き、WooCommerce の返金として自動記録します。全額返金は注文を返金済みにします。換算された決済のダッシュボードでの一部返金は注文メモのみです。対応額を WooCommerce の "Refund manually" で記録してください。

ライセンスキー

vibefox.net の VibeFox ライセンスキーで動作します。ライセンス欄は WooCommerce > Settings > Payments > KOMOJU Payment の上部です。License key にキーを貼り付け Activate をクリックします。欄には有効期限やドメインなどの状態を表示します。Check now で再確認、Change key で別のキーを入力、Remove key でサイトから削除します。Manage licenses and domains in your account で vibefox.net アカウントを開きます。

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

有効なキーがないと、購入者のチェックアウトに KOMOJU は表示されません。それでも決済が開始されると This payment method is not available. Please choose another one. が表示されます。ログイン中のストア管理者には (unlicensed — visible to admins only) 付きで表示され、キー購入前に設定・テストできます。プラグイン一覧と WooCommerce ページに通知が出ます。既存注文には影響せず、開始済み決済の確定と返金は機能します。

ライセンス期限後も動作しますが、更新とサポートには延長が必要です。状態はバックグラウンドで自動再確認します。

トラブルシューティング

チェックアウトに KOMOJU が表示されない：有効なライセンス、Enable/Disable の有効化、現在のモードの秘密キー（サンドボックスは Sandbox Secret Key、本番は Live Secret Key）を確認します。通貨は KOMOJU 対応である必要があります。不足は設定ページで警告します。

決済済みなのに注文がPending payment：ウェブフックが動作していません。ダッシュボードで該当モードのウェブフック、設定と完全一致する URL、イベント選択を確認します。適切な欄（Live Webhook Secret Token または Sandbox Webhook Secret Token）のトークンを確認し、WooCommerce > Status > Logs のソース wcp_komoju_payment を参照します。カードは帰還時も確定しますが、コンビニと振込はウェブフックのみです。

ウェブフックが Failed to verify KOMOJU webhook signature を返す：トークンがないか別のウェブフックのものです。KOMOJU が通知を再試行します。

ウェブフックが Mode mismatch, ignored を返す：注文の支払いと別モードのトークンで署名されています。本番とテストは別々のウェブフックとトークンを使ってください。

ウェブフックが Order is busy, retry later または Temporary error, retry later を返す：別のリクエストが注文を更新中、またはその時点で決済を確認できませんでした。KOMOJU が通知を再試行します。

注文が On hold：メモを確認します。払込票の支払い待ち、ダッシュボードでのキャプチャ待ち、金額・通貨の不一致、キャンセル後の支払いが考えられます。

返金が失敗する：メッセージを確認します。支払いモードの秘密キーがない、自動返金できない（ダッシュボードで返金）、換算決済で全額返金のみ可能、といった原因があります。

ライセンス欄にエラー：表示に従います。他ドメインで使用中なら vibefox.net で枠を解放して Check now をクリックします。サイトアドレス変更時は Check now で新ドメインを有効化します。ライセンスサーバーに接続できない場合、最後に確認した状態で動作します。

開発者は komoju_p_supported_currencies フィルターで通貨一覧を、komoju_p_session_params フィルターで決済方法などのセッション内容を変更できます。

アンインストール

無効化ではすべてのデータを保持します。削除するには Plugins ページで無効化して削除します。本プラグインのライセンスキーと状態は常に削除します。ゲートウェイ設定とログは Delete data on uninstall が有効だった場合のみ削除し、それ以外は再インストール用に保持します。既存注文の決済メモと取引 ID は残ります。

KOMOJU は各所有者の商標です。本プラグインは KOMOJU と提携しておらず、KOMOJU の承認を受けていません。