VibeFox Windcave for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

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

Windcave アカウント: REST API の認証情報を持つ Windcave 加盟店アカウントが必要です。API ユーザー名と API キーです。Windcave は UAT テスト環境（uat.windcave.com）と本番環境（sec.windcave.com）用にそれぞれ別々に発行します。Windcave サポートまたはアカウント担当者にお問い合わせください。PxPay のキーはこのモジュールでは使用できません。提供したい決済方法（カード、ウォレットなど）は、Windcave アカウントで有効になっている必要があります。

通知: Windcave が決済通知を送信できるよう、ストアはインターネットから到達可能である必要があります。Windcave 側で設定する必要はありません。

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

インストール

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

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

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

4. REST API のユーザー名とキーを入力します。テストモードでは UAT の認証情報を、実際の決済では本番環境の認証情報を入力します（設定を参照）。

5. 取引タイプと決済方法を選び、Enable/Disable を有効にして Save をクリックします。Test mode を有効にした状態でテスト決済を行い、その後 Test mode を無効にして実際の決済を受け付けます。

インストール時に、モジュールは注文ステータス Windcave payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを提供します。これらは Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。テストモードが有効な間は、ページに Test mode が有効です：決済は Windcave UAT 環境に送られ、実際の料金は請求されません。 と表示されます。モジュールは有効になっているものの、現在のモードに API ユーザー名またはキーがない場合、ページには決済方法が購入手続きで非表示になることの警告が表示されます（例：Windcave は有効ですが、UAT API ユーザー名 / キーが空のため、決済方法は購入手続きで非表示になります。）。Title は空にできません。空の場合、ページには 決済方法のタイトルを入力してください。 と表示され、何も保存されません。

Windcave

Enable/Disable: Enable Windcave payments で決済方法を有効または無効にします。初期値：無効。

Title: 購入手続きで購入者に表示される決済方法名です。注文に保存される決済方法名にもなります。初期値：Credit/Debit Card (Windcave)。必須。

Description: 購入手続きで決済方法の下に表示されるテキストです。初期値：You will be redirected to the secure Windcave payment page to complete your payment.

Windcave REST API

Windcave から発行された REST API の認証情報（ユーザー名と API キー。PxPay のキーではありません）を入力します。本番環境と UAT の認証情報は並べて保存できます。テストモードでは UAT の認証情報のみを、本番モードでは本番環境の認証情報のみを使用します。このセクションには Windcave REST API のドキュメントへのリンクがあります。

Test mode: Windcave UAT テスト環境（uat.windcave.com）を使用します。実際の料金は請求されません。新しい決済には UAT の認証情報が使われます。返金とキャプチャは、注文が支払われた環境に対して常に行われます。初期値：無効。

Production API username: sec.windcave.com 用の REST API ユーザー名です。

Production API key: sec.windcave.com 用の REST API キーです。

UAT API username: uat.windcave.com 用の REST API ユーザー名です（テストモード）。

UAT API key: uat.windcave.com 用の REST API キーです（テストモード）。

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

Clear saved keys: Production API key または UAT API key にチェックを入れ、Save をクリックすると削除されます。フィールドが空の場合は、保存された値が維持されます。

Notification URL: Windcave が決済通知（Fail-Proof Result Notification）を送信する宛先アドレスを表示します。フレンドリー URL を使用している場合は、https://your-shop/module/wcp_windcave_payment_gateway/notification のような形になります。Windcave 側での設定は不要です。モジュールは決済セッションごとに、戻り先アドレスとこの通知アドレスを送信します。このアドレスはインターネットから到達可能である必要があります。そうでない場合、注文は購入者が Windcave から戻ったときにのみ確認されます。購入者の戻りも通知も Windcave による署名はないため、モジュールはそれらだけを信頼することはありません。モジュールは常に、セッションを作成した環境の認証情報を使って、Windcave REST API からセッションの結果を取得します。

Payment

Transaction type: 決済の請求方法です。初期値：Purchase。

Payment methods: Windcave の決済ページに表示される方法です：Cards、Account2Account（ニュージーランドの銀行振込）、Apple Pay、Google Pay、PayPal、Alipay、WeChat Pay、UnionPay、Interac、humm。Ctrl または Cmd を押しながらクリックすると、複数選択できます。これらの方法は Windcave アカウントで有効になっている必要があります。フィールドを空にすると、アカウントで有効になっているすべての方法が表示されます。初期値：Cards。

Advanced

Debug log: API リクエストと決済イベントを、モジュールフォルダ内の logs/windcave_p_debug.log.php に記録します。このファイルはウェブから開くことはできません。この設定が無効の間は、エラーと警告のみが記録されます。API キー、カード情報、顧客の個人情報は記録されません。初期値：無効。

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

Clean uninstall: モジュールのアンインストール時に、モジュールの設定とログを削除します。注文とともに保存された決済データ（返金に必要な Windcave の取引 ID）は、常に保持されます。初期値：無効。

モジュールのバージョンはページ下部に表示されます。

購入手続き

支払い手続きで購入者は、説明付きの決済方法（初期値は Credit/Debit Card (Windcave)）を選択します。テストモードでは、購入者には Test mode: 決済は Windcave UAT 環境に送られ、実際の料金は請求されません。 も表示されます。確定すると、モジュールはカートの合計金額をカートの通貨で Windcave 決済セッションとして作成し、購入者を Windcave Hosted Payment Page に移動させます。カート番号は加盟店参照番号として送信され、ストアの言語、購入者の氏名、メールアドレス、電話番号、請求先住所も送信されます（カートに配送が必要な場合は配送先住所も送信されます）。この時点ではまだ注文は存在しません。

決済後、購入者はストアに戻ります。注文は Windcave が確認した後にのみ支払い済みとしてマークされます。モジュールは、購入者が戻ったときと Windcave からの通知が届いたときの両方で、REST API に問い合わせてセッションの結果を取得します。カートごとのロックにより、決済は一度だけ適用されます。その後注文が作成され、購入者には標準の注文確認ページと Your Windcave payment has been received. が表示されます。保留中の注文（承認、またはカートと一致しない決済）の場合、ページには Your payment was received by Windcave. The shop will check it before processing your order — please do not pay again. と表示されます。

承認された決済の後で購入者が戻ったものの、結果がまだ分からない場合は、Payment confirmation ページに We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. と、Check again ボタンが表示されます。通知は、Windcave が決済を確認するとすぐに注文を作成します。

購入者が決済を完了せずに戻った場合、購入手続きのページには次のいずれかのメッセージが表示されます。カートは保持されます。

購入者は同じカートで再試行できます。新しい試行では、まず前回のセッションを確認します。既に支払い済みであれば注文が作成され、2 回目の決済は開始されません。購入者が決済ページを一度も使用しておらず、カートも変更されていない場合は、同じページに戻されます。その時点で前回の決済が確認中であれば、購入者には Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again. と表示されます。

Windcave が決済を開始できない場合、購入者は購入手続きに留まり、短いメッセージが表示されます。Windcave がこの注文の情報で決済を開始できなかったこと、または決済サービスが一時的に利用できないことが示されます。理由はログに記録されます。現在のモードに認証情報がない場合、購入者には This payment method is not available at the moment. Please choose another payment method or contact us. と表示されます。

通知は、ストアがメンテナンスモードの間も機能し、ストアの国による制限でブロックされることはありません。

本モジュールには、サブスクリプションや定期決済、保存済みカード、サイト上への埋め込みカードフォーム（購入者は常に Windcave のページで支払います）、PxPay 2.0 API のサポートはなく、追加料金も発生しません。Windcave が追加料金を加えた場合、注文はメインの取引と照合されます。

注文と返金

Order statuses

No order yet: 購入者は Windcave に移動しましたが、まだ支払っていないか、Windcave がまだ決済を確認していないか、決済が拒否、キャンセル、または期限切れになりました。カートのみが存在します。

Payment accepted: Purchase の決済が確認され、カートと一致しています。決済は Windcave の取引 ID で記録され、メモには金額、取引 ID、承認コード、マスクされたカード番号付きのカード種別、環境（UAT または本番）が表示されます。

Windcave payment on hold (authorised): Auth の決済は承認されましたが、まだキャプチャされていません。キャプチャされるまで、注文に決済は記録されません。メモには、キャプチャまたは解除の方法が説明されています。

Windcave payment on hold (does not match): Windcave が報告した金額、通貨、加盟店参照番号、または取引タイプが、カートと異なります（例：決済の開始後に、別のタブでカートが変更された場合）。メモには違いが一覧表示されます。カートの通貨での Purchase の場合、決済は Windcave が実際に請求した金額で記録されます。発送の前に Windcave Payline で決済を確認し、必要に応じて返金してください。

Refunded: 決済が全額返金されたか、モジュールを通じて承認が解除されました。

キャンセルされた注文に対して承認済みの決済が届いた場合、または既存の注文に対して 2 回目の承認済み決済が届いた場合、注文は変更されません。取引 ID を含むメモは、Windcave Payline で返金するよう求めます（またはキャンセルされた注文を手動で復元するよう求めます）。

Windcave payment block

注文ページには Windcave payment ブロックが表示されます。取引 ID、セッション ID、取引タイプ、環境付きのステータス、支払い金額、承認コードとカード、キャプチャまたは取り消しの取引、決済合計と返金額、テスト決済用の Test mode (UAT) バッジ、返金履歴、カートのすべての Windcave セッション、注文の Windcave notes が含まれます。

Capture (Auth mode)

Windcave payment on hold の注文で、承認がまだキャプチャも解除もされていない場合、ブロックには金額とともに Capture Windcave payment が表示されます。クリックして Capture the authorised amount through Windcave now? を確認すると、承認された金額がキャプチャされます（決済が注文と一致しない場合を除き、注文の合計額）。注文は Payment accepted に移り、決済はキャプチャの取引 ID で記録されます。Windcave がキャプチャを受け付けない場合、ブロックには理由とともに Windcave capture failed: が表示され、その理由はメモに追加され、注文は保留のままになります。

Refunds

Windcave payment ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via Windcave をクリックします。Refund this amount through Windcave? This cannot be undone. の確認に応答してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。モジュールのページへのアクセスは必要ありません。返金は、Windcave が承認した金額と通貨を基準に計算されます。そのため、不一致が生じた後は、注文の合計ではなく、購入者が実際に支払った金額まで返金できます。キャプチャ後の返金は、キャプチャの取引に対して行われます。返金は、決済が行われた環境（UAT または本番）とアカウントに送信されるため、その環境の認証情報が保存されている必要があります。成功した返金は、返金履歴とメモに Windcave の取引 ID とともに追加されます。全額返金すると、注文は Refunded になります。一部返金ではステータスは変わりません。

キャプチャされていない Auth の決済の場合、ボタンは Release authorisation (void) となり、全額のみ解除できます。一部の金額を指定するとエラーになり、全額を返金するか、先に決済をキャプチャするよう求められます。

Windcave が返金を拒否した場合、ブロックには理由とともに Windcave declined the refund: が表示され、返金は記録されません。Windcave がまだ返金を処理中の場合、ブロックには Windcave has not confirmed the refund yet. See the order notes. が表示され、返金は記録されません。Windcave Payline で取引を確認してください。承認されていれば返金を手動で記録し、承認されていなければもう一度お試しください。同じ返金を繰り返し試みても、Windcave に 2 回送信されることはありません。

本モジュールはクレジットメモを作成しません。注文ページにある PrestaShop の標準の返金ボタンでは、Windcave を通じて返金されません。Windcave Payline で行われた返金は、ストアには通知されません。

ライセンスキー

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

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

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

トラブルシューティング

購入手続きに Windcave が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードで両方の認証情報が入力されていることを確認してください。テストモードでは UAT API username と UAT API key、本番モードでは Production API username と Production API key です。設定ページには、これらが不足している場合に警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループに対して許可されているかを確認してください。

決済は完了したが、注文が作成されていない: モジュールはまだ Windcave から結果を取得できていません。モジュールのページにある Log フィールドを確認してください。エラーは常に記録されます（例：セッションを検証できなかった場合）。決済の環境の認証情報が保存されており、正しいことを確認してください。この確認は、Windcave が通知を再送したとき（モジュールはエラーコードとともに payment could not be verified yet, retry later と応答するため、Windcave は再試行します）、購入者が Check again をクリックしたとき、同じカートで購入者が新しく決済を開始したときに繰り返されます。サーバーは、設定に表示された Notification URL への Windcave からのリクエストを受け付ける必要があります。

通知が order not found を返す: そのセッションは、このストアによって作成されたものではありません。例えば、同じ Windcave アカウントを使用している別のストアのセッションです。その通知は無視されます。

ログに Authentication failed がある: REST API のユーザー名またはキーが間違っているか、別の環境のものです。UAT の認証情報はテストモードでのみ、本番の認証情報は本番モードでのみ有効です。PxPay のキーは使用できません。

購入者に、Windcave がこの注文の情報で決済を開始できなかったと表示される: Windcave がセッションのリクエストを拒否しました。例えば、通貨や、アカウントで有効になっていない決済方法が原因です。正確な理由はログにあります。

決済後に注文が Windcave payment on hold になる: Windcave payment ブロックのメモを確認してください。決済がキャプチャを待っている Auth か、支払い金額、通貨、または加盟店参照番号がカートと異なっていたかのいずれかです。決済をキャプチャ、発送、または返金してください。

テスト決済と本番決済: UAT と本番は分けて管理されます。各セッションは作成された環境で確認され、返金とキャプチャは、後から Test mode を切り替えた場合でも、決済の環境に対して行われます。

環境に関するメッセージが出て返金が失敗する: 決済は UAT または本番で行われており、その環境の認証情報が保存されていません。認証情報を入力してから、もう一度お試しください。

注文ブロックに Capture Windcave payment が表示されない: このボタンは、Auth で支払われ、まだキャプチャも解除もされていない Windcave payment on hold の注文にのみ表示され、注文を編集できる従業員にのみ表示されます。

詳細の確認先: エラーと警告は常にログに記録されます。API リクエストと決済イベントも記録するには、Debug log を有効にしてください。

アンインストール

Modules > Module Manager に移動し、VibeFox Windcave Payment Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Clean uninstall が有効であれば、モジュールの設定とログが削除されます。無効であれば、後で再インストールできるように、すべての設定が保持されます。Windcave のセッション、取引、返金、および注文ステータス Windcave payment on hold は常に保持されるため、以前に支払われた注文は、再インストール後も返金とキャプチャが可能です。既存の注文は、決済のメモと取引 ID を保持します。

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