VibeFox Khipu for PrestaShop — ヘルプ

動作要件

PrestaShop： 8.0 から 9.x。

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

通貨： チリペソ（CLP）、アルゼンチンペソ（ARS）、ペルーソル（PEN）。それ以外の通貨のカートでは、チェックアウト時に支払い方法が表示されません。

Khipu アカウント： Khipu の集金アカウントの Receiver ID（「Id de cobrador」）、API key、Secret key が必要です。これらは Khipu アカウントの販売者プロフィール（khipu.com/merchant/profile）にあります。3 つすべてが必須です。Secret key がないと、どの支払いも確認できません。Khipu アカウント側で設定する必要はありません。

到達可能なショップ： Khipu はショップを呼び出して支払いを確認するため、通知 URL はパスワード保護や Khipu を遮断するファイアウォールなしでインターネットから到達可能である必要があります。ショップのメンテナンスモードはこれを妨げません。

VibeFox ライセンスキー： vibefox.net で購入します。1 つのキーで 1 つのドメインに対応します。

インストール

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

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

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

4. Khipu の集金アカウントの Receiver ID、API key、Secret key を入力します（設定の項を参照）。

5. Enable / Disable を有効にして Save をクリックします。まずテストする場合は Khipu 開発者アカウントのキーを使用し、その後で本番アカウントのキーに置き換えてください。

インストール時に、モジュールは注文ステータス Khipu payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループ向けに新しい支払いモジュールを有効にします。Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Khipu Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、Receiver ID、API key、Secret key が未入力の場合（その場合チェックアウトで Khipu は表示されません）や、ショップの既定通貨が Khipu でサポートされていない場合に、警告が表示されます。

Khipu

Enable / Disable： Enable Khipu payments で支払い方法を有効または無効にします。既定値：オフ。

Title： チェックアウトで購入者に表示される支払い方法の名前です。注文にも支払い方法名としてこの名前が保存されます。既定値：Khipu。必須。

Description： チェックアウトで支払い方法の下に表示されるテキストです。既定値：Pay by bank transfer with Khipu。

Khipu アカウント

Khipu の集金アカウント（khipu.com/merchant/profile）から Receiver ID、API key、Secret key をコピーします。Khipu には独立したサンドボックスサーバーがなく、モジュールにもテストモードの切り替えはありません。テストする場合は、開発者（「desarrollo」）の集金アカウントのキーを使用してください。このアカウントはテスト銀行 DemoBank で支払いを行い、実際の資金は動きません。公開する際には、本番の集金アカウントのキーに切り替えてください。

Receiver ID： Khipu の受取人（「cobrador」）ID です。ほかの Khipu アカウントへの支払いは拒否されます。

API key： 支払いの作成と、Khipu での各支払いの検証に使用されます。

Secret key： Khipu の支払い通知の署名（HMAC-SHA256）を検証するために使用されます。これがないと、どの支払いも確認できません。

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

Clear saved secrets： API key または Secret key にチェックを入れて Save をクリックすると削除されます。空欄の場合は保存済みの値が維持されます。

支払い通知

Notification URL： Khipu は、ここに表示された URL を呼び出して支払いを確認します。フレンドリー URL を使用している場合は https://your-shop/module/wcp_khipu_gateway/webhook のような形になり、言語コードが付くこともあります。この URL はすべての支払いに自動的に送信されるため、Khipu アカウントで設定すべきことはありませんが、URL はインターネットから到達可能である必要があります。

各通知には、Secret key で生成された有効な署名が必要です。有効な署名がない通知は拒否されます。モジュールは通知の内容を信用しません。Khipu に支払いステータスを問い合わせ、Khipu が報告した内容に従って動作します：

Status after payment： Khipu が支払いを確認したときに設定される注文ステータスです。ステータスはすぐに、ステータス変更 1 回で設定されます。

詳細設定

Debug log： API 呼び出しと通知を、モジュールフォルダー内の logs/wc_khp_debug.log.php に記録します。このファイルは Web から開くことはできません。エラーは、スイッチがオフでも常に記録されます。キーや支払者データは書き込まれません。既定値：オフ。

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

Delete data on uninstall： オンにすると、モジュールのアンインストール時にゲートウェイの設定とログが削除されます。注文データ（注文の Khipu 支払い ID）は常に保持されます。既定値：オフ。

チェックアウト

支払いの段階で、購入者は支払い方法（既定では Khipu）を、その説明とともに選択し、注文を確定します。モジュールは、カート通貨でのカート合計に対する Khipu の支払いを作成し、購入者を Khipu の支払いページへ送ります。Khipu では、支払いは Order # として、カート番号、ショップ名、商品一覧とともに表示されます。購入者のメールアドレスが有効な場合は Khipu に渡されます。Khipu のページで、購入者は自身の銀行から銀行振込で支払います。この時点ではまだ注文は存在しません。

支払い後、購入者はショップに戻ります。注文が支払い済みとしてマークされるのは、Khipu が確認した後だけです。署名付きの通知によって、または購入者が戻ったときに Khipu へステータスを問い合わせることによって確認されます。戻る操作そのものでは、何も支払い済みにはなりません。注文が作成されると、購入者には標準の注文確認ページが表示されます。銀行がまだ振込を確認中である場合や、Khipu に接続できない場合は、Payment confirmation ページに Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail. と表示され、Check again と Back to checkout のボタンが表示されます。カートの最新の Khipu 支払いをその注文と照合できない場合（たとえば別の Receiver ID に属している場合）、購入者は We could not match this payment to an order. If you paid, please contact us. というメッセージとともにチェックアウトに戻ります。

購入者が支払わずに Khipu のページを離れた場合、または支払いが完了しなかった場合、購入者は The Khipu payment was not completed. You can try again or choose another payment method. というメッセージとともにチェックアウトに戻ります。カートは保持されます。新しい試行では、以前の未払いの Khipu 支払いが削除されるため、古いリンクから支払うことはできなくなります。Khipu が以前の支払いをすでに受け取っていた場合は、注文が作成され、新たな支払いは行われません。以前の振込がまだ確認中の場合、購入者には Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again. と表示されます。

Khipu が支払いを作成できない場合、購入者は簡単なメッセージとともにチェックアウトに留まります。例：Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. または Khipu is temporarily unavailable. Please try again in a few minutes. 詳細はログに記録されます。

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

このモジュールは単発の銀行振込支払いのみに対応しています。返金は PrestaShop から Khipu へ送信されず、サブスクリプション、保存済み支払い方法、事前承認の機能もありません。未払いの支払いは在庫の確保とは関連付けられません。

注文

注文ステータス

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

Payment accepted or Delivered： Khipu が支払いを確認しました。ステータスは Status after payment に従います。支払いは Khipu の支払い ID を取引 ID として記録され、メモには Khipu payment verified. Payment ID: と、支払い ID および金額が表示されます。

Khipu payment on hold： Khipu が、注文の金額または通貨と一致しない支払いを確認しました（たとえば、支払いの開始後にカートが変更された場合）。または、注文がキャンセルされた後に支払いが届きました。実際に受け取った金額は注文に記録され（通貨が異なる場合は記録されません）、その理由がメモに記載されます。Khipu アカウントで支払いを確認してから、注文を完了するか、購入者に返金してください。同じカートについて、正しい金額の後続の支払いが届いた場合、注文は支払い済みステータスに移行します。

すでに支払い済みの注文、または支払い後にクローズされた注文に対して支払いが届いた場合、注文は変更されません。2 回目の支払いである場合は、購入者に返金するようメモで通知されます。Khipu が支払い済みの支払いを取り消されたと報告した場合、注文にはメモが追加され、ステータスは変更されません。

Khipu 支払いブロック

注文ページには Khipu payment ブロックが表示されます。このブロックには、注文のカートに対する Khipu の支払い試行（日付、金額、Khipu 支払い ID、Khipu のステータスと結果）、注文が Khipu payment on hold の間に表示される Manual review の警告、そして注文の Khipu notes が含まれます。このブロックは読み取り専用です。

返金

Khipu は API を通じて返金を提供していないため、返金は PrestaShop から Khipu へ送信されません。Khipu アカウントまたは銀行振込で購入者に返金してから、PrestaShop に返金を手動で記録してください。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Khipu が表示されない： ライセンスが有効であること、Enable / Disable がオンであること、Receiver ID、API key、Secret key がすべて入力されていることを確認してください。カートの通貨は CLP、ARS、PEN のいずれかである必要があります。設定ページには、何かが不足している場合に警告が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているか確認してください。

支払いは完了したが、注文が作成されなかった： Khipu は、銀行が振込を確認した後に確定します。注文は、Khipu の通知が届いたとき、または購入者が Check again をクリックしたときに作成されます。Notification URL に表示された URL で、ショップがインターネットから到達可能であることを確認してください（パスワード保護や Khipu を遮断するファイアウォールがないこと）。また、モジュールページの Log 欄も確認してください。

通知の応答が Secret key not configured： Secret key が空です。入力してください。Khipu は通知を再送します。

通知の応答が Invalid signature、Missing signature、Malformed signature： Secret key が、使用しているキーの集金アカウントのものではないか、リクエストが Khipu から送られたものではありません。

通知の応答が Order not found または Payment does not belong to this order： 支払いが別の Receiver ID または別のカートに対して行われました。Receiver ID を確認してください。

通知の応答が Payment not final yet または Verification unavailable： 振込がまだ確認中か、Khipu に接続できませんでした。Khipu は通知を再送します。

通知の応答が Busy, retry later または Order could not be created, retry later： 同じタイミングで別のリクエストが注文を確認していたか、注文を作成できませんでした（たとえばモジュールが無効になっている場合）。Khipu は通知を再送します。理由はログに記録されています。

注文が Khipu payment on hold： Khipu payment ブロックのメモを確認してください。金額または通貨が注文と一致しなかったか、注文がキャンセルされた後に支払いが届きました。

購入者に「Khipu payments are not available right now」と表示される： API key がないか、間違っています。Khipu アカウントでキーを確認してください。

Khipu アカウントが別の通貨（たとえば Khipu Spain の EUR）を受け付けている場合、開発者は actionWcpKhipuSupportedCurrencies フックを使ってその通貨を追加できます。

アンインストール

Modules > Module Manager に移動し、VibeFox Khipu Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、ゲートウェイの設定とログが削除されます。オフの場合は、後で再インストールするためにすべての設定が保持されます。Khipu の支払い試行と、注文ステータス Khipu payment on hold は常に保持されます。既存の注文は、支払いのメモと取引 ID を保持します。

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