VibeFox Kushki for WooCommerce — ヘルプ
要件
WordPress：6.0 以降。
WooCommerce：8.0 以降。インストールされていて有効であること。WooCommerce がないとプラグインは有効化できません。
PHP：8.0 以降。
ストア通貨：USD（エクアドル）または COP（コロンビア）。その他の通貨では、チェックアウト時に決済方法が表示されません。
HTTPS：Kushki は、ライブモードでチェックアウトが HTTPS で提供されることを求めています。
Kushki アカウント：Kushki のテスト（UAT）アカウントと本番アカウントの Public・Private Merchant ID が必要です。これらは Kushki Console の Developers > Credentials にあります。任意の Webhook を使う場合は、各アカウントの Webhook 署名キーも必要です（設定の項を参照）。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_kushki_payment フォルダを /wp-content/plugins/ にアップロードすることもできます。
2. Activate をクリックします。
3. 設定を開きます。WooCommerce > Settings > Payments > Kushki > Manage、またはプラグインページでプラグイン名の下にある Settings をクリックします。
4. ページ上部のライセンス欄に VibeFox ライセンスキーを入力し、Activate をクリックします。
5. テスト用の Public・Private Merchant ID を入力し、Test mode をオンのままにします。必要に応じて Kushki Console で Webhook を設定し、その署名キーを貼り付けます（設定の項を参照）。
6. Enable / Disable をオンにして、テスト注文を行います。準備が整ったら、ライブの Merchant ID（およびライブの Webhook 署名）を入力し、Test mode のチェックを外します。
設定
すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Kushki。決済方法が有効になっているのに現在のモードの Merchant ID が未入力の場合（その場合、決済方法はチェックアウトで非表示になります）、ストア通貨がサポートされていない場合、HTTPS なしでライブモードを使用している場合、現在のモードに Webhook 署名がない場合には、フィールドの上に警告が表示されます。テストモードがオンの間は、Test mode is on: the Kushki test environment is used, no real money is charged. と表示されます。決済方法が有効なまま、現在のモードの Merchant ID を入力せずに保存すると、入力を促すエラーが表示されます。ID の前後の空白は保存時に削除されます。
一般
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 認証情報
Kushki Console（Developers > Credentials）から Public・Private Merchant ID をコピーします。テスト（UAT）アカウントと本番アカウントでは ID が異なります。テストモードではテスト用の ID のみを、ライブモードではライブ用の ID のみを使用します。
Test mode: Use the Kushki test (UAT) environment をオンにすると、Merchant ID、カードフォーム、API がまとめて Kushki のテスト環境に切り替わります。実際の料金は請求されず、チェックアウトに 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 です。秘密にしてください。
Webhook（推奨）
支払いは Kushki API の応答によって直ちに確定するため、Webhook は必須ではありません。Webhook は、応答が失われた支払い（タイムアウトなど）の確認と、Kushki Console で行われた取り消しや返金の通知を追加で行います。Kushki Console（Webhooks）で、カード決済用として設定のこのセクションに表示される URL を追加します。形式は https://your-site/wc-api/webhook_kushki_p/ のようになります。テストアカウントと本番アカウントの両方で行ってください。
プラグインは次のカード通知を処理します：
Test webhook signature: Kushki テストアカウントの Webhook 署名キー（Console > Webhooks）。
Live webhook signature: Kushki 本番アカウントの Webhook 署名キー。
有効な署名のない Webhook は拒否されます。署名キーがない場合はすべての Webhook 通知が拒否されますが、支払いは API 応答で確定するため、引き続き機能します。
詳細設定
Debug log: Log API calls and webhooks をオンにすると、Kushki のリクエストと Webhook が WooCommerce > Status > Logs に、ソース wcp_kushki_payment として記録されます。エラーは常に記録されます。ログには Merchant ID、カードトークン、購入者のメールアドレスは一切含まれません。初期値：オフ。
Delete data on uninstall: オンの場合、プラグインを削除すると設定とログが削除されます。注文と Kushki の参照情報は残ります。初期値：オフ。
チェックアウト
購入者は決済方法を選択します（初期値は Credit / debit card (Kushki)）。その下に、注文通貨の注文合計金額が表示された Kushki のカードフォームが現れます。Pay for order ページでは、フォームは注文合計を使用します。購入者はカード情報を入力し、Kushki フォームが分割払いを提供している場合はそれを選択し、Kushki フォーム内の支払いボタンを押します。
クラシックチェックアウトでは、Kushki が選択されている間、WooCommerce の Place order ボタンは非表示になります。カードが受け付けられると、注文は自動的に送信されます。チェックアウトブロックでは、購入者は同様に Kushki フォーム内の支払いボタンを押します。これを行わずに注文しようとすると、Please enter your card details in the Kushki form and press its pay button. というメッセージが表示されます。
その後、ストアはサーバー側でカードに請求します。注文は、Kushki がチケット番号とともに確認した後にのみ支払い済みになり、購入者は直接注文完了ページに進みます。Kushki が承認された金額または通貨を報告した場合は、注文と照合されます。
カードが拒否された場合、購入者には Kushki からの理由とともに Your payment was declined が表示され、同じフォームで別のカードを試すことができます。ネットワーク、キー、サーバーの問題が発生した場合、購入者には The payment could not be processed right now. Please try again in a moment or choose another payment method. が表示されます。技術的な理由は注文メモとログに追加されます。支払い処理中にもう一度クリックすると、A payment for this order is already being processed. Please wait a moment and check your order status. が表示されます。
この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage（HPOS）に対応しています。3-D Secure、不正利用防止ルール、提供される分割払いは Kushki Console で設定します。
プラグインはワンステップのカード決済のみに対応しています。部分返金、保存済みカード、サブスクリプション、Add payment method には対応しておらず、現金払い、銀行振込（PSE）、デビットカードのリダイレクト決済にも対応していません。オーソリとキャプチャの分離もできません。
注文と返金
注文ステータス
Pending payment: 注文は作成されていますが、カードはまだ請求されていません。
Processing: Kushki が請求を確認しました（API 応答または Webhook による）。ダウンロード可能な仮想商品のみの注文は、WooCommerce の既定どおり Completed になります。注文メモには、モード、Kushki のチケット番号、参照番号が表示されます。トランザクション ID は Kushki のトランザクション参照番号（またはチケット番号）です。
On hold: Kushki がチケット番号なしで成功を返したか、注文と異なる金額または通貨を報告しました。注文メモに理由が記載されています。Kushki Console で取引を確認し、注文を処理するか、支払いを返金してください。
Failed: カードが拒否されたか、請求を行えませんでした。注文メモには Kushki のコードとメッセージが表示されます。購入者は再度支払うことができます。
すでに支払い済み、キャンセル済み、または返金済みの注文について、Webhook が別の承認済み請求を報告した場合、その注文は変更されません。メモで二重請求がないか確認し、Kushki Console で返金するよう求められます。ライブの注文に対してテスト環境からの Webhook が届いた場合（またはその逆）は、メモ付きで無視されます。
返金
注文を開き、Refund をクリックして注文合計の全額を入力し、Refund via Credit / debit card (Kushki) をクリックします（ボタンには Title の設定値が表示されます）。Kushki は支払い全額を返金するため、全額返金のみ受け付けます。部分的な金額の場合、プラグインは Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. を表示します。1 回の支払いに対する返金は 1 回のみ可能です。
返金は支払いが行われたモード（テストまたはライブ）で送信されるため、そのモードの Private Merchant ID が設定されている必要があります。Kushki が返金を受け付けない場合、WooCommerce がエラーを表示し、返金は記録されません。返金に成功すると、Kushki の返金チケットとともに注文メモに追加されます。
Kushki Console で行われた取り消しや返金は Webhook で届き、注文メモに追加されます。WooCommerce の返金として自動的に記録されるわけではありません。
ライセンスキー
このプラグインは vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンス欄は WooCommerce > Settings > Payments > Kushki の上部にあります。キーを License key に貼り付けて Activate をクリックします。欄には、ライセンスの有効期限日などの状態と、お使いのドメインが表示されます。Check now で状態を再確認、Change key で別のキーを入力、Remove key でこのサイトからキーを削除できます。Manage licenses and domains in your account のリンクから vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、Kushki はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. が表示されます。ログイン中のストア管理者には、(unlicensed — visible to admins only) と表示された状態で決済方法が引き続き表示されるため、キーを購入する前にプラグインの設定とテストができます。プラグインページと WooCommerce のページには通知が表示されます。既存の注文には影響しません。Webhook は引き続き処理され、返金も機能します。
ライセンスの期限が切れてもプラグインは動作し続けますが、アップデートとサポートには更新が必要です。状態はバックグラウンドで自動的に再確認されます。
トラブルシューティング
チェックアウトに Kushki が表示されない：ライセンスが有効であること、Enable / Disable がオンであること、現在のモードに両方の Merchant ID があることを確認してください。テストモードではテスト用の ID、ライブモードではライブ用の ID が必要です。ストア通貨（または Pay for order ページの注文通貨）が USD または COP であることも確認します。設定ページには、これらの問題ごとに警告が表示されます。
支払いは完了したのに、注文が Failed になっているか Pending payment のままになっている：タイムアウトなどにより Kushki API の応答が失われています。Webhook はこの種の支払いを確認します。Kushki Console で、Webhook の URL が設定に表示されたものと完全に一致していること、使用しているモードのアカウント用であること、そのアカウントの署名キーが対応するフィールド（Test webhook signature または Live webhook signature）に入力されていることを確認してください。支払われた金額と通貨がない承認済み請求の場合、注文は代わりに保留になります。
Webhook が Webhook signature not configured と応答する：Webhook 署名がどちらも設定されていません。署名キーを設定に貼り付けてください。
Webhook が Invalid signature と応答する：署名キーが別のアカウントまたはモードのものか、通知が途中で変更されています。
Webhook が Order mismatch と応答する：この通知はこの注文のものではありません（注文キーまたはトランザクションが誤っています）。注文は変更されません。
Webhook が Busy, retry later と応答する：同じタイミングで別のリクエストがこの注文を処理していました。Kushki は通知を再送することがあります。
カードフォームが読み込まれない：購入者には The Kushki card form could not be loaded. Please reload the page or choose another payment method. が表示されます。現在のモードの Public Merchant ID を確認してください。
購入者に This payment option is not available in this store. Please pay by card. と表示される：Kushki フォームでカード以外の支払い方法が選択されました。プラグインはカードのみを請求します。
購入者が支払い時にエラーを見る：注文メモを開くか、Debug log をオンにして WooCommerce > Status > Logs を確認してください（ソースは wcp_kushki_payment）。Private Merchant ID が誤っているか未入力の場合は、支払いを処理できなかったという一般的なメッセージになります。
返金がモードに関するメッセージで失敗する：支払いはテストまたはライブモードで行われましたが、そのモードの Private Merchant ID が設定されていません。入力してからもう一度お試しください。
返金が No Kushki ticket number found for this order で失敗する：この注文には確認済みの Kushki 請求がありません。Kushki Console で返金してください。
その他の通貨：開発者は kushki_p_supported_currencies フィルターで通貨リストを変更できますが、自己責任となります。その通貨が Kushki アカウントで有効になっている必要があります。
ライセンス欄にエラーが表示される：欄内のメッセージに従ってください。たとえば、キーがすでに別のドメインで使用されている場合は、vibefox.net のアカウントで枠を解放してから Check now をクリックします。サイトのアドレスが変わった場合は、Check now をクリックして新しいドメインでキーを有効化します。ライセンスサーバーに接続できない場合は、最後に確認された状態でプラグインが動作し続けます。
アンインストール
プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。このプラグインのライセンスキーとライセンス状態は常に削除されます。決済方法の設定とログは、Delete data on uninstall がオンになっていた場合にのみ削除されます。それ以外の場合は、後で再インストールする際のために残ります。既存の注文は、支払いのメモ、Kushki のチケット番号、トランザクション ID を保持します。
Kushki は各所有者の商標です。このプラグインは Kushki と提携しておらず、Kushki による承認も受けていません。