VibeFox Khipu for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。

PHP: 8.0 以降。

通貨: チリ・ペソ（CLP）、アルゼンチン・ペソ（ARS）、またはペルー・ソル（PEN）。この通貨は System > Localisation > Currencies に存在している必要があります。Khipu は、お客様がこれらの通貨のいずれかで支払う場合にのみ提供されます。それ以外の通貨では、チェックアウトで支払い方法が表示されません。

Khipu アカウント: Khipu の収納（cobro）アカウントの Receiver ID（"Id de cobrador"）、API key、secret key が必要です。これらは Khipu アカウントの加盟店プロフィール（khipu.com/merchant/profile）にあります。3 つすべてが必要です。1 つでも欠けると、チェックアウトで Khipu は提供されず、secret key がなければどの支払いも確認できません。Khipu アカウント側で設定する必要はありません。

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

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

インストール

ダウンロードは 1 つの zip ファイルで、両方の OpenCart バージョン用のパッケージが含まれています。お使いのコンピューターで展開してください。含まれるのは README.txt、OpenCart 3 用パッケージ wcp_khipu_gateway-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_khipu_gateway.ocmod.zip です。お使いの OpenCart バージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer に進み、Upload をクリックして wcp_khipu_gateway-oc3-(version).ocmod.zip ファイルを選択します。この拡張機能には OCMOD の変更が含まれないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions に進み、タイプとして Payments を選択します。VibeFox Khipu Gateway を見つけて Install（緑色の + ボタン）をクリックします。管理者ユーザーには、支払い拡張機能の一覧を変更する権限が必要です。

3. Edit（鉛筆ボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（License key を参照）。

4. Khipu 収納アカウントの Receiver ID、API key、Secret key を入力します（Configuration を参照）。

5. Enable / Disable をオンにして Save をクリックします。先にテストする場合は、Khipu デベロッパーアカウントのキーを使用し、その後で本番アカウントのキーに置き換えてください。

OpenCart 4

1. 管理画面で Extensions > Installer に進み、Upload をクリックして wcp_khipu_gateway.ocmod.zip ファイルを選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。

2. 同じページのインストール済み拡張機能の一覧にパッケージが表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に進み、タイプとして Payments を選択します。VibeFox Khipu Gateway を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆ボタン）をクリックします。

4. ライセンスキーと Khipu のキーを、OpenCart 3 の手順 3 から 5 と同じように入力します。設定ページとそのフィールドは両方のバージョンで同じです。異なるのは通知 URL だけです（支払い通知を参照）。

新規インストールでは、支払い方法はオフの状態で始まります。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit。セクションは左側に一覧表示され、一覧の下にある Save ボタンでページ全体が保存されます。設定の上には、Receiver ID、API key、secret key のいずれかが欠けている場合（この場合、チェックアウトで Khipu は提供されません）や、ストアの既定の通貨が Khipu でサポートされていない場合（この場合、Khipu はお客様が CLP、ARS、PEN で支払う場合にのみ提供されます）に警告が表示されます。拡張機能を変更する権限がない場合、ページは設定を表示しますが保存はできません。

保存時には、Title は空にできず、128 文字を超えてはならず、Sort Order は整数である必要があり、Total は 0 以上の数値である必要があり、地理区域と注文ステータスが存在している必要があります。条件を満たさない場合は何も保存されず、ページに該当する項目が表示されます。キーが未入力でも保存はできます。

Khipu

Enable / Disable: Enable Khipu payments で支払い方法のオン／オフを切り替えます。既定値：オフ。

Title: チェックアウト時にお客様に表示される支払い方法の名前です。注文に保存される支払い方法名にもなります。既定値：Khipu。必須、1 〜 128 文字。

Description: Confirm Order ステップで、確認ボタンの上にお客様に表示されるテキストです。既定値：Khipu による銀行振込でお支払いいただけます。

Sort Order: チェックアウトの支払い方法の中で Khipu が表示される位置です。空欄のままにするか、整数を入力してください。

Geo Zone: 選択した Geo Zone の支払い先住所に対してのみ Khipu を提供します。既定値：All zones。Geo Zone は System > Localisation > Geo Zones で設定します。

Total: Khipu を提供するために注文が達している必要がある、ストアの既定通貨でのチェックアウト合計金額です。空欄にすると、どの金額でも Khipu を提供します。

Khipu アカウント

Khipu の収納アカウントから Receiver ID、API key、secret key をコピーします（このセクションは khipu.com/merchant/profile へのリンクを含みます）。Khipu には独立したサンドボックスサーバーがなく、この拡張機能にもテストモードのスイッチはありません。テストするには、デベロッパー（"desarrollo"）の収納アカウントのキーを使用します。そのアカウントはテスト銀行 DemoBank で支払いを行い、実際の資金は動きません。本番稼働に移行する際は、本番の収納アカウントのキーに切り替えてください。

Receiver ID: Khipu の受取人（"cobrador"）ID です。他の Khipu アカウントへの支払いは拒否されます。

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

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

保存されたキーは再度表示されることはありません。フィールドは空のまま Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。保存済みのキーを削除するには、フィールドの下にある Clear the saved value にチェックを入れて Save をクリックします。

支払い通知

Notification URL: Khipu は、ここに表示される URL を呼び出して支払いを確認します。OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_khipu_gateway/webhook、OpenCart 4 では https://your-store/index.php?route=extension/wcp_khipu_gateway/payment/wcp_khipu_gateway.webhook のような形式で、OpenCart インストールのストアフロントのアドレスから組み立てられます。この URL はすべての支払いとともに自動的に送信されるため、Khipu アカウントで設定すべきことはありませんが、インターネットから到達可能である必要があります。

すべての通知には、Secret key で作成された有効な署名が必要です。有効な署名のない通知は拒否されます。拡張機能は通知の内容を決して信用せず、Khipu に支払いステータスを問い合わせ、Khipu が報告した内容に従って処理します：

Status after payment: Khipu が支払いを確認したときに注文が受け取るステータスです。ステータスは 1 回のステータス変更で直ちに設定されます。

OpenCart は Confirm Order ステップで注文を作成しますが、この時点ではステータスはありません（欠落注文）。注文がステータスを受け取るのは、Khipu が支払いを確認した後だけです。以下の各フィールドには、お使いの OpenCart 注文ステータスが一覧表示されます。

Paid Order Status: Status after payment が Processing の場合、確認済みの支払い後のステータスです。既定値：処理中。

Complete Order Status: Status after payment が Completed の場合、確認済みの支払い後のステータスです。既定値：完了。

On Hold (Review) Status: 金額または通貨が注文と一致しない支払い、または注文のキャンセル後に届いた支払いには、このステータスと理由を説明するメモが設定されます。既定値：OpenCart には「保留」ステータスがないため、保留中。独自のステータスは System > Localisation > Order Statuses で作成し、ここで選択できます。

詳細設定

Debug log: API 呼び出しと通知を、OpenCart のログフォルダ（storage/logs）にある wc_khp_debug.log.php に記録します。このファイルは Web から開くことはできず、5 MB に達すると wc_khp_debug.old.log.php に移動されます。エラーは、スイッチがオフでも常に記録されます。キーと支払人のデータは決して書き込まれません。既定値：オフ。

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

Delete data on uninstall: オンにすると、拡張機能をアンインストールしたときにゲートウェイの設定とログが削除されます。注文データ（注文の Khipu 支払い ID）は常に保持されます。既定値：オフ。

インポート / エクスポート

Export: Download JSON で設定を JSON ファイルとして保存します。API key と secret key はエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みの API key と secret key は保持されます。

チェックアウト

Payment Method ステップで、お客様は支払い方法を選択します（既定では Khipu）。Confirm Order ステップでは、お客様に確認ボタンの上にあなたの説明が表示されます。OpenCart はこのステップで、まだステータスのない注文を作成します。お客様が Confirm Order をクリックすると、拡張機能は注文通貨で注文合計額に対する Khipu の支払いを作成し、お客様を Khipu の支払いページに移動させます。Khipu 上では、支払いは注文番号とストア名、および商品一覧とともに Order # として表示されます。お客様のメールアドレスは、有効な場合に Khipu に渡されます。Khipu のページでは、お客様は自分の銀行から銀行振込で支払います。

OpenCart 4 では、お客様は支払い方法ブロックの Choose ボタンで、Payment method options ウィンドウから支払い方法を選択し、チェックアウトページ下部の Confirm Order をクリックします。

支払いが完了すると、お客様はストアに戻ります。注文は、Khipu が確認した後にのみ支払い済みとしてマークされます。確認は、署名付きの通知によるか、お客様が戻ったときに Khipu へのステータス照会によって行われます。戻る操作そのものでは、何も支払い済みとしてマークされません。その後、注文は OpenCart の標準的な方法でステータスを受け取り、通常の注文メールと在庫の更新が行われ、お客様には OpenCart の注文完了ページが表示されます。銀行がまだ振込を確認中である場合、または Khipu に接続できない場合は、Payment confirmation ページに Khipu is confirming your bank transfer. Your order will be confirmed 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. と表示されたチェックアウトに戻されます。カートは保持されます。OpenCart 4 では、これらのメッセージはチェックアウトページの上部に表示されます。新しい試行のたびに（OpenCart 3 では Confirm Order ステップが表示されるたびに新しい注文が作成され、OpenCart 4 はチェックアウトの注文を更新して新しい Khipu 支払いで支払います）、その注文またはカートの以前の未払いの Khipu 支払いは削除されるため、古いリンクでは支払えなくなります。Khipu が以前の支払いをすでに受け取っていた場合、その支払いが適用され、お客様は新たな支払いなしで完了ページに進みます。以前の振込がまだ銀行で確認中の場合、お客様には Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again. と表示されます。以前の支払いが審査中の場合、お客様は再度支払う前にストアに連絡するよう求められます。同じカートに対して変更（数量の変更を含む）があった場合は、独自の支払いを必要とする新しいカートとして扱われます。

OpenCart 4 は、成功ページが表示されるまで注文をチェックアウトに保持します。その間に支払いなしで注文が閉じられていた場合（たとえばストアがキャンセルした場合）、お客様は Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. と表示されるチェックアウトに戻されます。注文がすでに確定していて、その後カートが変更されている場合、メッセージは Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. です。どちらの場合も、次の Confirm Order でカートの新しい注文が支払われます。

Khipu が支払いを作成できない場合、お客様は Confirm Order ステップに留まり、ボタンの上に 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. などの短いメッセージが表示されます。詳細はログに記録されます。

ストアがメンテナンスモードの間も、通知は機能します。OpenCart 3 は支払い拡張機能のリクエストを通過させ、OpenCart 4 では、拡張機能が通知とお客様の戻りを通過させるスタートアップアクションを追加します。

この拡張機能は、一回限りの銀行振込による支払いのみに対応しています。返金は OpenCart から Khipu には送信されず、サブスクリプション、保存済みの支払い方法、事前承認はありません。未払いの支払いは在庫の引き当てとは関連付けられません。

注文

注文ステータス

ステータスなし（欠落注文）: お客様は Khipu に移動しましたが、まだ支払っていない、または Khipu がまだ振込を確認していない状態です。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。

Paid Order Status または Complete Order Status（既定値 処理中 または 完了）: Khipu が支払いを確認しました。ステータスは Status after payment に従います。メモには Khipu payment verified. Payment ID: と支払い ID および金額が表示されます。

On Hold (Review) Status（既定値 保留中）: Khipu が、金額または通貨が注文と一致しない支払いを確認した場合、または注文のキャンセルや拒否の後に支払いが届いた場合です。メモにその理由が記載されます。Khipu アカウントで支払いを確認し、その後で注文を完了するか、お客様に返金してください。同じ注文に正しい金額の支払いが後から届いた場合、注文は支払い済みのステータスに移り、お客様にはメールで通知されます。支払いが、注文が別の処理ステータスに変更された後に届いた場合、ステータスは変わらず、メモが追加されるだけです。

すでに支払い済みの注文、または支払い済みのカートの別の注文に対して支払いが届いた場合、注文は変更されません。それが 2 回目の支払いである場合、メモがお客様への返金を求めます。Khipu が支払い済みの支払いを取り消されたと報告した場合、注文にはメモが設定され、ステータスは変わりません。

メモは、お客様には表示されない注文の History の項目です。Khipu という語で始まります。

VibeFox Khipu Gateway タブ

Sales > Orders で、Khipu で支払われた注文を開きます。注文ページの下部、History と Additional の隣に表示される VibeFox Khipu Gateway タブには、注文の Khipu 支払い試行（日付、金額、Khipu 支払い ID、Khipu ステータスと結果）、注文がレビューステータスにある間は Manual review の警告、そして注文の Khipu notes が表示されます。このタブは読み取り専用で、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

Khipu は API を通じた返金を提供していないため、返金は OpenCart から Khipu には送信されません。タブにはその旨が表示されます。Khipu アカウントまたは銀行振込でお客様に返金し、その後で OpenCart の注文ステータスを手動で変更してください。

ライセンスキー

この拡張機能は、vibefox.net から取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Khipu Gateway は、Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはキーがマスクされた状態で、ステータス（例：ライセンスの有効期限日とお使いのドメイン）と、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-payment-khipu の行と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、拡張機能に対する Modify 権限を持つ管理者ユーザーだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれています）。

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

1 つのキーは 1 つのドメインで使用できます。ドメインとは、OpenCart の設定にあるストアのアドレスのことです。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウト時に Khipu はお客様に表示されません。それでも支払いが開始された場合、お客様には This payment method is not available. Please choose another one. と表示されます。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアで支払い方法が (unlicensed — visible to admins only) と表示された状態で引き続き表示されるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理者のログインを認識しないため、有効なキーがない場合、支払い方法は全員に対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。すでに開始された支払いは引き続き確認されます。

ライセンスの期限が切れても拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は毎日、その後は毎週確認されます。Cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに Khipu が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、Receiver ID、API key、Secret key がすべて入力されていることを確認してください。お客様は CLP、ARS、PEN で支払う必要があります。設定ページには、何かが欠けている場合に警告が表示されます。支払い先住所が選択された Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

支払いは完了したが、注文のステータスがない: 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 not found for this account、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 updated, retry later: 注文が同時に別のリクエストで確認されていたか、注文ステータスを設定できませんでした。Khipu は通知を再送します。理由はログにあります。

支払い後に注文がレビューステータスになっている: VibeFox Khipu Gateway タブのメモを確認してください。金額または通貨が注文と一致しなかった、または注文のキャンセル後に支払いが届いたなどが考えられます。

お客様に "Khipu payments are not available right now" と表示される: API key が欠落しているか誤っています。Khipu アカウントでキーを確認してください。

開発者向け：拡張機能は OpenCart イベント wc_khp_supported_currencies（Khipu アカウントが受け付ける通貨を追加するため。例：Khipu スペイン用の EUR）、wc_khp_currency_decimals、wc_khp_payment_data を発行します。

アンインストール

Extensions > Extensions に進み、タイプ Payments を選択して、VibeFox Khipu Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自体の設定を常に削除します：Enable / Disable、Sort Order、Geo Zone、Total、および 3 つの注文ステータス（再インストール時に既定値に戻ります）。OpenCart 4 では、そのイベントと、メンテナンスモードで通知とお客様の戻りを通過させるスタートアップアクションも削除されます。Delete data on uninstall がオンの場合は、残りのゲートウェイ設定（タイトル、説明、Receiver ID、キー、支払い後のステータス、デバッグログ）とログも削除されます。オフの場合は、後で再インストールする際のために保持されます。Khipu の支払い試行は常に保持されるため、以前に支払われた注文に関する遅延した通知は、再インストール後も引き続き処理されます。既存の注文は、支払いメモを保持します。

OpenCart 4 では、ファイルも削除するには、アンインストール後に Extensions > Installer に進み、インストール済み拡張機能の一覧で VibeFox Khipu Gateway の横の Uninstall（オレンジ色の − ボタン）をクリックしてから、Delete（赤いゴミ箱ボタン）をクリックして、アップロードされたパッケージを削除します。

Khipu は、その各所有者の商標です。この拡張機能は Khipu とは提携しておらず、Khipu による承認や推奨も受けていません。