VibeFox KOMOJU for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x まで。

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

KOMOJU アカウント：秘密キー（sk_live_...、テストモードでは sk_test_...）と、KOMOJU ダッシュボードで作成したウェブフックのシークレットトークンが必要です（設定を参照）。公開可能キーは不要です。KOMOJU が貴店のウェブフック URL に到達できる必要があります。

カート通貨：JPY、USD、EUR、TWD、KRW、PLN、GBP、HKD、SGD、NZD、AUD、IDR、MYR、PHP、THB、CNY、BRL、CHF、CAD、VND。それ以外の通貨のカートでは決済方法は表示されません。

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

インストール

1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

2. アップロードが完了したら Configure をクリックするか、後でモジュールの一覧から VibeFox KOMOJU Payment を探して Configure をクリックします。

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

4. KOMOJU ダッシュボードで、Webhook URL セクションに表示された URL とイベントを指定してウェブフックを追加し、そのシークレットトークンをコピーします（設定を参照）。

5. 本番用の秘密キーと本番用ウェブフックのシークレットトークン、およびテストモード用のテスト用キーを入力します。Enable/Disable をオンにして、Save をクリックします。

インストール時にモジュールは 2 つの注文ステータス、Awaiting KOMOJU payment と KOMOJU payment on hold を作成します。PrestaShop は新しい決済モジュールを、その時点で有効な国にのみ紐づけます。後から有効にした国は、Payment > Preferences でモジュールのチェックボックスをオンにする必要があります。そこで通貨や顧客グループを制限することもできます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox KOMOJU Payment > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、テストモードがオンの間 KOMOJU Sandbox Mode is enabled. と表示されます。現在のモードに秘密キーがない場合（その場合、チェックアウトで決済方法は非表示になります）、またはウェブフックのシークレットトークンがない場合（その場合、KOMOJU の通知は拒否され、コンビニ払いと銀行振込は確定しません）、さらに KOMOJU がショップの既定通貨に対応していない場合（その場合、その通貨のカートでは決済方法が非表示になります）には警告を表示します。

KOMOJU 決済

Enable/Disable：Enable KOMOJU Payment Gateway で決済方法のオン／オフを切り替えます。既定：オフ。

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 にあります（先に、Webhook URL セクションに表示されたウェブフック 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)。既定：オフ。オンの間、チェックアウトでは説明文の上に Test mode と表示されます。

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

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

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

保存済みのシークレットを削除：キーまたはトークンにチェックを入れ、Save をクリックすると削除されます。空のフィールドは保存済みの値を維持します。

ウェブフック URL

ウェブフックは、遅延したコンビニ払いや銀行振込を含め、決済に関する情報をショップに通知します。KOMOJU ダッシュボードの Settings > Webhooks で、このセクションに表示された URL を本番用とテストモード用の両方に追加します。フレンドリー URL を使用している場合、次のような形になります：https://your-shop/module/wcp_komoju_payment/webhook。言語コード（例：/en/）が付くこともあります。URL は設定画面に表示されたとおりに正確にコピーしてください。その後、各ウェブフックのシークレットトークンを Live Webhook Secret Token または Sandbox Webhook Secret Token にコピーします。

次のイベントを選択します（このセクションにも記載されています）：

期限切れ、キャンセル、失敗のイベントは、注文の現在の決済に対してのみ注文を変更します。そのため、以前の試行の決済が、別の方法で支払われている注文をキャンセルすることはありません。有効な署名のないウェブフックは拒否されます。どちらかのシークレットトークンで署名されたウェブフックは受け付けられますが、同じモードの決済に対してのみです。ウェブフックがない場合、カード決済は購入者がショップに戻ったときに引き続き確定しますが、コンビニ払いと銀行振込は確定しません。

詳細設定

Invoice Prefix：KOMOJU に送信される注文番号の接頭辞で、その後にカート番号が続きます。同じ KOMOJU アカウントで複数のショップを使用する場合は、ショップごとに一意にしてください。既定：PS-。

Enable Logging：KOMOJU のイベントと API 呼び出しを、モジュールフォルダー内の logs/komoju_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。キーと購入者データは記録されません。エラーと警告は常に書き込まれます。既定：オフ。

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

Delete data on uninstall：オンにすると、モジュールをアンインストールしたときにゲートウェイの設定とログが削除されます。注文、KOMOJU の取引と返金、注文ステータスは常に残るため、再インストール後も古い注文を確定・返金できます。既定：オフ。

チェックアウト

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

支払い後、購入者は貴店に戻ります。モジュールは決済のモードのキーを使って、KOMOJU API から決済セッションを読み取ります。注文は、KOMOJU が確認した後にのみ支払い済みになります：署名付きウェブフックによるか、購入者が戻った際のセッション読み取りによります。その後注文が作成され、購入者には標準の注文確認ページが表示され、Your payment with KOMOJU has been received. と表示されます。その時点で KOMOJU に接続できない場合、Payment confirmation ページに 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. と表示され、Check again ボタンが表示されます。

コンビニ払いと銀行振込の場合、購入者には払込票が届きます。注文は Awaiting KOMOJU payment で作成され、確認ページでは KOMOJU の案内に従って支払いを完了するよう伝えられます（例：コンビニや銀行振込で）。購入者が支払い、KOMOJU がウェブフックを送信すると、注文は Payment accepted になります。払込票の期限が切れた場合や、後に決済が失敗した場合、確認ページには Your KOMOJU payment was not completed. Please contact us about this order. と表示されます。

決済が完了しなかった場合、購入者は The payment was not completed. You can try again or choose another payment method. と表示されたチェックアウトに戻ります。カートは保持されます。合計額が変わっていなければ、新しい試行は開いている KOMOJU セッションを再利用します。古い合計額のセッションは 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. です。技術的な理由はログに書き込まれます。

決済から確認までの間にカートのクーポンが無効になった場合、PrestaShop はそのクーポンを注文から削除します。購入者は割引価格で支払っているため、注文には KOMOJU payment on hold とメモが付けられます。

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

本モジュールには、サイト上のカードフォーム、保存済みカード、定期購入はありません。決済方法を制限することもありません。決済方法は KOMOJU のページで選ばれます。手動キャプチャ操作もありません。手動キャプチャ用に承認された決済は KOMOJU ダッシュボードでキャプチャする必要があり、それまで注文は Awaiting KOMOJU payment のままです。

注文と返金

注文ステータス

No order yet：購入者は KOMOJU に移動しましたが、まだ支払っていないか、KOMOJU がまだ決済を確認していません。カートだけが存在します。

Payment accepted：KOMOJU が決済を確認しました。決済は KOMOJU の決済 ID を取引 ID として記録され、メモには決済 ID、決済方法、確認方法（ウェブフックまたは帰還）が表示されます。

Awaiting KOMOJU payment：コンビニ払いまたは銀行振込の払込票が発行され、支払いを待っている状態、または決済が KOMOJU ダッシュボードでのキャプチャを待っている状態です。

KOMOJU payment on hold：KOMOJU が注文合計と異なる金額または通貨を報告した場合（例：決済開始後にカートが変更された）、クーポンが削除された場合、または注文がキャンセルされた後に決済がキャプチャされた場合です。メモに理由が記載されています。注文を確認して処理するか、決済を返金してください。

Canceled：払込票の期限が切れたか、決済がキャンセルされました。

Payment error：既存の注文の決済が失敗しました。

Refunded：注文画面または KOMOJU ダッシュボードで、決済が全額返金されました。

すでに支払い済みの注文に対して 2 回目の決済がキャプチャされた場合、注文は変更されません。重複である場合は、KOMOJU ダッシュボードで返金するよう、メモで案内されます。返金済みの注文が再度開かれることはありません。

KOMOJU 決済ブロック

注文画面には KOMOJU payment ブロックが表示され、KOMOJU の決済 ID（KOMOJU ダッシュボードの決済へのリンク付き）と、決済方法、セッション、KOMOJU 側の注文番号、ステータス、支払額、返金額、テスト決済用の Test mode バッジ、返金履歴、注文の KOMOJU notes が表示されます。

返金

KOMOJU payment ブロックで金額を入力し（まだ返金されていない金額が自動で入力されます）、必要に応じて理由を入力して、Refund via KOMOJU をクリックします。Refund this amount through KOMOJU? This cannot be undone. という確認に応じてください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。返金は、KOMOJU が実際に請求した金額が上限です。そのため金額の不一致の後は、注文合計ではなく、購入者が支払った金額まで返金できます。返金は、決済が行われたモードのキーで送信されるため、そのモードの秘密キーが設定されている必要があります。モジュールはまず KOMOJU で決済を確認し、まだ返金可能な金額を超える返金を拒否します。KOMOJU が決済を自動で返金できない場合（コンビニ払いなど一部の方法では購入者の銀行情報が必要です）、KOMOJU のエラーメッセージが表示され、何も記録されません。そのような返金は KOMOJU ダッシュボードで処理してください。返金は、KOMOJU が確認した時点でのみ完了とみなされます。成功した返金は返金履歴とメモに追加されます。全額返金は注文を Refunded に設定します。一部返金ではステータスは変わりません。返金は、KOMOJU が決済をキャプチャした後に利用できます。

KOMOJU が別の通貨に換算した決済（例：EUR のカートに対する JPY でのコンビニ払い）の場合、PrestaShop からできるのは全額返金のみです。一部返金は KOMOJU ダッシュボードで行ってください。

本モジュールはクレジットスリップを作成しません。注文画面の標準の PrestaShop 返金ボタンは、KOMOJU を通じて返金しません。

KOMOJU ダッシュボードで行った返金は、ウェブフックで届き、メモ付きで返金履歴に追加されます。決済全体が返金されると、注文は Refunded に設定されます。別の通貨に換算された決済について、ダッシュボードで行った一部返金は注文にメモされるだけです。対応する金額を PrestaShop で手動で記録してください（クレジットスリップ）。

ライセンスキー

本モジュールは、vibefox.net で取得した VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox KOMOJU Payment は、Modules > Module Manager > VibeFox KOMOJU Payment > Configure ページの上部、設定の上にある最初のブロックです。キーを License key に入力し、Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限日や、お使いのドメインなど）、および次のボタンが表示されます。Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）。その下には Product: presta-payment-komoju の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。キーを変更できるのは、このモジュールの Configure 権限を持つスタッフだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。

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

1 つのキーは 1 つのドメインで使用できます。ドメインとはメインショップのドメインを指し、マルチストア構成でも同様です。ショップからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。

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

ライセンスの期限が切れると、モジュールは引き続き動作しますが、アップデートとサポートには更新が必要です。ステータスは、管理画面での作業中に自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに KOMOJU が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに秘密キーがあることを確認してください。テストモードでは Sandbox Secret Key、本番モードでは Live Secret Key です。カート通貨は KOMOJU が対応している必要があります。不足があると設定ページに警告が表示されます。Payment > Preferences で、モジュールがカート通貨、購入者の国、購入者のグループに対して許可されているか確認してください。

決済は完了したのに注文が作成されない：ウェブフックが動作していません。KOMOJU ダッシュボードで、使用しているモードのウェブフックが存在し、その URL が Webhook URL セクションに表示されたものと完全に一致し、イベントが選択されていることを確認してください。そのシークレットトークンが対応するフィールド（Live Webhook Secret Token または Sandbox Webhook Secret Token）に入っているか確認し、モジュールのページにある Log フィールドを確認してください。カード決済は購入者がショップに戻ったときにも確定しますが、コンビニ払いと銀行振込はウェブフックでのみ確定します。

ウェブフックの応答 Failed to verify KOMOJU webhook signature.:シークレットトークンがないか、別のウェブフックのものです。KOMOJU は通知を再送します。

ウェブフックの応答 Mode mismatch, ignored.:ウェブフックは、決済が行われたモードとは別のモードのシークレットトークンで署名されています。本番モードとテストモード用に別々のウェブフックとトークンを使用し、取り違えていないか確認してください。

ウェブフックの応答 Order is busy, retry later. または Temporary error, retry later.:注文は別のリクエストによって更新中でした、その時点で注文を作成できなかった（例：モジュールが無効）、または決済を確認できませんでした。KOMOJU は通知を再送します。理由はログにあります。

ブラウザでウェブフック URL にエラーが表示される：これは正常です。この URL は KOMOJU からの署名付きリクエストのみを受け付けます。

注文が KOMOJU payment on hold または Awaiting KOMOJU payment になっている：注文ブロックの KOMOJU notes を確認してください。払込票が支払いを待っている、決済が KOMOJU ダッシュボードでのキャプチャを待っている、金額または通貨が一致しなかった、クーポンが削除された、または注文がキャンセルされた後に決済が届いた、などの理由があります。

返金に失敗する：メッセージを確認してください。決済が行われたモードの秘密キーが設定されていない、決済を自動で返金できない（KOMOJU ダッシュボードで返金してください）、設定されたキーでは KOMOJU がその決済を認識できない、または換算された決済では全額返金しかできない、といった原因が考えられます。

開発者は、通貨の一覧を actionKomojuPSupportedCurrencies フックで、また決済方法などの決済セッションを actionKomojuPSessionParams フックで変更できます。

アンインストール

Modules > Module Manager に移動し、VibeFox KOMOJU Payment の横のメニューを開いて Uninstall を選びます。本モジュールのライセンスキーとライセンスステータスは、常に削除されます。Delete data on uninstall がオンの場合、ゲートウェイの設定とログが削除されます。オフの場合、後で再インストールできるように、すべての設定が保持されます。KOMOJU の取引と返金、注文ステータス Awaiting KOMOJU payment と KOMOJU payment on hold は常に保持されるため、再インストール後も古い注文を確定・返金できます。既存の注文は、決済メモと取引 ID を保持します。

KOMOJU は各所有者の商標です。本モジュールは KOMOJU と提携しておらず、KOMOJU による推奨も受けていません。