VibeFox Kushki for PrestaShop — ヘルプ

要件

PrestaShop：8.0 ～ 9.x。

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

通貨：USD（エクアドル）または COP（コロンビア）。それ以外の通貨のカートでは、チェックアウトで決済方法が表示されません。

HTTPS：Kushki は、本番モードではチェックアウトを HTTPS で提供することを必須としています。

Kushki アカウント：Kushki のテスト（UAT）アカウントと本番アカウントの Public・Private Merchant ID が必要です。これらは Kushki Console の Developers > Credentials にあります。任意の Webhook を使う場合は、各アカウントの Webhook 署名キーも必要です（設定を参照）。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後から行う場合は、モジュール一覧で VibeFox Kushki Payment を探して Configure をクリックします。

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

4. テスト用の Public・Private Merchant ID を入力し、Test mode をオンのままにします。必要に応じて、Kushki Console で Webhook を設定し、その署名キーを貼り付けます（設定を参照）。

5. Enable / Disable をオンにして Save をクリックし、テスト注文を行います。準備ができたら、本番の Merchant ID（と本番の Webhook 署名）を入力し、Test mode をオフにします。

インストール時に、モジュールは注文ステータス Kushki payment on hold を作成します。PrestaShop は、新しい決済モジュールをショップの通貨、国、顧客グループに割り当てます。Payment > Preferences で、モジュールが USD または COP、およびエクアドルまたはコロンビアに対して許可されていることを確認してください。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Kushki Payment > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。フィールドの上では、決済方法が有効なのに現在のモードの Merchant ID が不足している場合（その場合、決済方法はチェックアウトで非表示になります）、ショップの既定通貨が USD または COP でない場合、HTTPS なしで本番モードを使用している場合、現在のモードに Webhook 署名がない場合に、ページが警告を表示します。テストモードがオンの間は、テストモードがオンです：Kushki のテスト環境が使用され、実際の料金は請求されません。 と表示されます。決済方法が有効で、現在のモードの Merchant ID が未入力のまま保存すると、設定は保存されますが、入力を促すメッセージが表示されます。ID の前後の空白は保存時に削除されます。

Kushki

Enable / Disable：Enable Kushki card payments で決済方法のオン・オフを切り替えます。既定値：オフ。

Title：チェックアウトで購入者に表示される決済方法名です。注文にも保存される決済方法名になります。既定値：Credit / debit card (Kushki)。必須。

Description：チェックアウトでカードフォームの上に表示されるテキストです。既定値：Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

API 認証情報

Public・Private Merchant ID は、Kushki Console（Developers > Credentials）からコピーします。テスト（UAT）アカウントと本番アカウントでは ID が異なります。テストモードではテスト用の ID のみを使用し、本番モードでは本番用の ID のみを使用します。

Test mode：Kushki のテスト（UAT）環境を使用します。テスト用の Merchant ID、テスト用のカードフォーム、テスト用の API がまとめて使われます。実際の料金は請求されず、チェックアウトには TEST MODE のバッジが表示されます。既定値：オン。実際の支払いを受け付けるにはオフにします。返金は常に支払いが行われた環境で処理されます。

Test Public Merchant ID：Kushki テストアカウントの Public Merchant ID です。カードフォームの読み込みに使われます。

Test Private Merchant ID：Kushki テストアカウントの Private Merchant ID です。請求と返金のためにサーバー側で使われます。

Live Public Merchant ID：Kushki 本番アカウントの Public Merchant ID です。

Live Private Merchant ID：Kushki 本番アカウントの Private Merchant ID です。秘密に管理してください。

保存済みの Private Merchant ID と Webhook 署名は、再度表示されることはありません。フィールドは空のままになり、保存済み — そのままにするには空欄のままにしてください。 と表示されます。変更する場合にのみ新しい値を入力します。

Webhook（推奨）

支払いは Kushki API の応答により直ちに確定するため、Webhook は必須ではありません。Webhook は、応答が失われた支払い（例：タイムアウト）について注文を作成し、Kushki Console で行われたキャンセルや返金を通知するためにも使われます。Kushki Console（Webhooks）で、カード決済用に Webhook URL に表示された URL を追加します。フレンドリー URL を使用している場合、URL は https://your-shop/module/wcp_kushki_payment/webhook のような形になり、/es/ のような言語コードが付くこともあります。URL は設定に表示されたとおりに、正確にコピーしてください。テストアカウントと本番アカウントの両方で行ってください。

モジュールは次のカード通知を処理します：

Test webhook signature：Kushki テストアカウントの Webhook 署名キーです（Console > Webhooks）。

Live webhook signature：Kushki 本番アカウントの Webhook 署名キーです。

Clear saved secrets：Private Merchant ID または Webhook 署名にチェックを入れ、Save をクリックすると削除されます。空のフィールドは保存済みの値を維持します。

有効な署名のない Webhook は拒否されます。通知は支払いが行われたモードのキーで署名されている必要があるため、テスト通知が本番の支払いを確定させることはありません。署名キーがない場合、すべての Webhook 通知は拒否されますが、支払いは API 応答によって確定されるため、引き続き機能します。

詳細設定

Debug log：Kushki のリクエストと Webhook を、モジュールフォルダ内の logs/kushki_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。エラーは常に記録されます。ログに Merchant ID、カードトークン、購入者のメールアドレスが含まれることはありません。既定値：オフ。

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

Delete data on uninstall：オンの場合、モジュールをアンインストールすると設定とログが削除されます。Kushki の支払い記録（請求と返金）と注文ステータス Kushki payment on hold は常に残るため、再インストール後も古い注文を返金できます。既定値：オフ。

チェックアウト

支払いステップで、購入者は決済方法を選択します（既定では Credit / debit card (Kushki)）。その下に Kushki のカードフォームが表示され、カート通貨でのカート合計が示されます。購入者はカード情報を入力し、Kushki のフォームが提供している場合は分割払いを選択して、Kushki フォーム内の支払いボタンを押します。

PrestaShop の Place order ボタンは、利用規約を含むため表示されたままになります。利用規約がすでに同意済みの場合、支払いは Kushki の支払いボタンの後に自動的に送信されます。そうでない場合、購入者には Kushki がカードを承認しました。利用規約に同意し、「Place order」を押して支払いを完了してください。 と表示されます。購入者が Kushki フォームを使わずに Place order を押した場合は、Kushki フォームにカード情報を入力し、その支払いボタンを押してください。 というメッセージが表示されます。

その後、ショップはサーバー側でカードに請求します。注文は、Kushki がチケット番号とともに確定した後にのみ支払い済みとしてマークされます。注文が作成されると、購入者には標準の注文確認ページが表示され、カード決済を受け付けました。 と示されます。Kushki が承認された金額や通貨を報告した場合は、カートと照合されます。保留中の注文には、お支払いを確認中です。確認が完了次第、注文を更新いたします。 と表示されます。

カードが拒否された場合、注文は作成されず、購入者は支払いステップに戻り、お支払いが拒否されました と Kushki からの理由が表示されます。別のカードを試すことができます。ネットワーク、キー、サーバーの問題が発生した場合、購入者には 現在お支払いを処理できません。しばらくしてから再度お試しいただくか、別の決済方法をお選びください。 と表示されます。技術的な理由はログに書き込まれます。支払い処理中にもう一度クリックすると、この注文の支払いは処理中です。少々お待ちいただき、注文ステータスをご確認ください。 と表示されます。

Kushki の応答が失われた場合（例：タイムアウト）、購入者には一般的なメッセージが表示されますが、請求の試行は保持されます。署名付きの Webhook が承認された請求を通知すると、注文が作成されます。すでに注文があるカート、または注文がまだ作成されていない承認済みの請求については、再度請求されることはありません。購入者には、その注文の確認が表示されます。Webhook が届く前に購入者が再度支払った場合、それは新しい請求になります。最初の請求の遅延承認は、二重請求の可能性についてのメモを追加するだけです。

Webhook は、ショップがメンテナンスモードの間も機能し、ショップの国別制限によってブロックされることはありません。3-D Secure、不正利用ルール、提供される分割払いは、Kushki Console で設定します。

モジュールはワンステップのカード決済のみに対応しています。部分返金、保存済みカードやサブスクリプション、現金、銀行振込（PSE）、デビットカードのリダイレクト決済、オーソリとキャプチャの分離には対応していません。

注文と返金

注文ステータス

No order yet：購入者が支払っていない、カードが拒否された、または Kushki の応答が失われて Webhook がまだ届いていない状態です。カートのみが存在します。

Payment accepted：Kushki が請求を確定しました（API 応答または Webhook による）。支払いは、Kushki の取引リファレンス（またはチケット番号）を取引 ID として記録されます。メモには、モード、Kushki のチケット番号、リファレンスが表示されます。

Kushki payment on hold：Kushki がチケット番号なしで成功を返した、カートと異なる金額または通貨を報告した、または支払い中にカートが変更されました。メモで理由が説明されます。Kushki Console で取引を確認し、注文を処理するか、支払いを返金してください。後から、チケット番号と一致する金額を伴う署名付きの承認が届くと、注文は Payment accepted になります。

Payment error：Webhook が、保留中の注文の請求が拒否されたことを通知しました。

Refunded：モジュールを通じて支払いが返金されました。

すでに支払い済み、キャンセル済み、または返金済みの注文について、Kushki が別の承認済みの請求を報告した場合、注文は変更されません。メモで二重請求の確認と、Kushki Console での返金が求められます。本番の支払いに対するテスト環境からの Webhook（またはその逆）は、メモ付きで無視されます。

Kushki 支払いブロック

注文ページには Kushki payment ブロックが表示され、チケット番号、取引リファレンス、環境（テスト支払いには Test バッジ付き）、請求のステータス、請求額と注文合計、返金フォーム、返金履歴、注文の Kushki notes が含まれます。

返金

Kushki は請求全体を返金するため、全額返金のみ可能です。Kushki payment ブロックには、Kushki が請求した金額が入力されています。必要に応じて理由を入力し、Refund via Kushki をクリックして、Kushki で支払い全額を返金しますか？この操作は取り消せません。 という確認に同意してください。注文を編集する権限が必要です。それ以外の金額の場合、モジュールは金額とともに Kushki では支払い全額のみ返金できます。請求された全額を入力してください と表示し、何も送信しません。返金は Kushki が請求した金額と通貨で行われるため、金額に差異がある場合、購入者が受け取るのは注文合計ではなく、実際に請求された金額です。支払いは 1 回のみ返金できます。

返金は支払いが行われたモード（テストまたは本番）で送信されるため、そのモードの Private Merchant ID が設定されている必要があります。Kushki が返金を受け付けない場合、ブロックには Kushki のコードとメッセージとともに Kushki の返金に失敗しました が表示され、返金は記録されません。返金が成功すると、Kushki の返金チケットとともに返金履歴とメモに追加され、注文は Refunded に設定されます。返金には、チケット番号付きで確定した Kushki の請求が必要です。

モジュールはクレジットメモを作成しません。注文ページの標準の PrestaShop 返金ボタンでは、Kushki を通じて返金されません。Kushki Console で行われたキャンセルや返金は Webhook で届き、メモに追加されます。注文ステータスは自動的には変更されません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Kushki が表示されない：ライセンスが有効であること、Enable / Disable がオンであること、現在のモードに両方の Merchant ID があることを確認してください。テストモードではテスト用の ID、本番モードでは本番用の ID が必要です。カート通貨が USD または COP であることを確認してください。Payment > Preferences で、モジュールがカート通貨、購入者の国、購入者のグループに対して許可されていることを確認してください。ID が不足している場合、設定ページに警告が表示されます。

支払いは完了したが、注文が作成されなかった：Kushki API の応答が失われました（例：タイムアウト）。このような支払いについては、Webhook が注文を作成します。Kushki Console で、Webhook URL が Webhook URL に表示されたものと正確に一致していること、使用しているモードのアカウント用であること、そのアカウントの署名キーが対応するフィールド（Test webhook signature または Live webhook signature）に入力されていることを確認してください。支払い済みの金額と通貨がない承認済みの請求は、Kushki payment on hold の注文を作成します。

Webhook の応答が Webhook signature not configured：どちらの Webhook 署名も設定されていません。署名キーを設定に貼り付けてください。

Webhook の応答が Invalid signature：署名キーが別のアカウントまたはモードのものであるか、通知が送信中に変更されました。

Webhook の応答が Order mismatch：通知がこのカートの請求に属していません（試行キーまたは取引が正しくありません）。何も変更されません。

Webhook の応答が Busy, retry later：同じ瞬間に別のリクエストが注文を処理していたか、注文を作成できませんでした（例：モジュールが無効になっている）。Kushki は通知を再送することがあります。エラーは常にログに書き込まれます。

ブラウザで Webhook URL に POST とだけ表示される：これは正常です。この URL は Kushki からの通知のみを受け付けます。

カードフォームが読み込まれない：購入者には Kushki のカードフォームを読み込めませんでした。ページを再読み込みするか、別の決済方法をお選びください。 と表示されます。現在のモードの Public Merchant ID を確認してください。

購入者に「この決済方法はこのストアでは利用できません。カードでお支払いください。」と表示される：Kushki フォームでカード以外の決済方法が選択されました。モジュールはカードのみを請求します。

購入者に支払い時のエラーが表示される：Debug log をオンにして、モジュールページの Log フィールドを確認してください。Private Merchant ID が誤っているか未入力の場合、支払いを処理できなかったという一般的なメッセージが表示されます。

購入者に「お支払いは受け付けられましたが、注文を自動で完了できませんでした」と表示される：Kushki は請求を承認しましたが、PrestaShop は注文を作成できませんでした。理由はログに表示されます。同じカートの次回の支払い試行では、再請求せずに注文が作成されます。

モードに関するメッセージで返金が失敗する：支払いはテストモードまたは本番モードで行われましたが、そのモードの Private Merchant ID が設定されていません。入力してから再試行してください。

返金が提供されず、「この注文の Kushki チケット番号が見つかりません」と表示される：この注文には確定した Kushki の請求がありません。Kushki Console で返金してください。

アンインストール

Modules > Module Manager に移動し、VibeFox Kushki Payment の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。Kushki の支払い記録（請求と返金）と注文ステータス Kushki payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いメモ、Kushki のチケット番号、取引 ID を保持します。

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