VibeFox Culqi for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。

PHP: 8.0 以降。

ストアの通貨: ペルー・ソル（PEN）または米ドル（USD）が、貴店で有効な通貨である必要があります。Culqi はそれ以外の通貨を受け付けず、購入者が PEN または USD で支払う場合にのみ決済方法が表示されます。

Culqi アカウント: Culqi アカウントの公開キーと秘密キーが必要です。インテグレーション（テスト）用のキーは integ-panel.culqi.com から、本番（ライブ）用のキーは mipanel.culqi.com から、CulqiPanel > Desarrollo > API Keys で取得します。公開キーはブラウザ内の Culqi ポップアップで使用されます。秘密キーはサーバーでのみ使用され、ブラウザに送信されることはありません。ウェブフックは不要です。

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

インストール

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

OpenCart 3

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

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

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

4. インテグレーションキーを貼り付けます。実際の決済を行う場合は本番キーも貼り付けます（設定を参照）。

5. Enable/Disable をオンにして Save をクリックします。テスト中は Test Mode をオンのままにし、実際の決済を受け付ける際にオフにします。

OpenCart 4

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

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

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

4. ライセンスキーと Culqi のキーを、OpenCart 3 のステップ 3 から 5 と同じように入力してください。設定ページとそのフィールドは両バージョンで同じです。

新規インストール直後は、決済方法がオフ、テストモードがオンの状態です。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit。セクションは左側に一覧表示されます。一覧の下にある Save ボタンで、ページ全体を保存します。テストモードがオンの間、設定の上部には Test mode is active: the integration keys are used and no real money is charged. と表示されます。ゲートウェイが有効なのに現在のモードのキーが未入力の場合や、有効な店舗の通貨がいずれも Culqi でサポートされていない場合には警告が表示されます。どちらの場合も、チェックアウトでは決済方法が非表示になります。デフォルトの通貨が PEN や USD でない場合、ページには、購入者がサポートされている通貨で支払う場合にのみ Culqi が提供されると表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時、不正な値は保存されず、以前の値が保持されます。その他のフィールドは保存されます。ページには、そのようなフィールドごとにエラーが表示されます。例：接頭辞の誤ったキー（例：Live Secret Key must start with sk_live_ — the previous value was kept.）、空または 128 文字を超える Title、整数ではない Sort Order、0 以上の数値ではない Total、存在しない地域（ジオゾーン）や注文ステータス。

Culqi

Enable/Disable: Enable Culqi Payment Gateway は、決済方法のオン／オフを切り替えます。デフォルト：オフ。

Title: チェックアウトで購入者に表示される決済方法の名称です。注文に保存される決済方法名にもなります。デフォルト：Credit/Debit Card or Yape (Culqi)。必須。128 文字まで。

Description: Confirm Order のステップで、確認ボタンの上に購入者へ表示されるテキストです。デフォルト：Pay securely with your credit/debit card or Yape via Culqi.

Sort Order: チェックアウトで表示される決済方法の中での Culqi の表示順です。空欄にするか、整数を入力します。

Geo Zone: 選択したジオゾーン内の請求先住所に対してのみ Culqi を提供します。デフォルト：All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。

Total: Culqi を提供するために注文が達している必要がある、ストアのデフォルト通貨での合計金額です。空欄にすると、どの金額でも Culqi を提供します。

API キー

CulqiPanel > Desarrollo > API Keys からキーをコピーします。インテグレーション（テスト）用キーは integ-panel.culqi.com、本番キーは mipanel.culqi.com にあります（ページからリンクされています）。テストモードではテスト用キーのみを使用し、ライブモードではライブ用キーのみを使用します。各キーは、その入力欄の接頭辞で始まる必要があります。

Test Mode: オンのとき、テスト用キー（pk_test_ / sk_test_）を使用し、実際の料金は請求されません。デフォルト：オン。本番キーで実際の決済を受け付けるにはオフにします。オンの間、購入者には Confirm Order のステップで TEST MODE: No real charges will be made. と表示されます。

Test Public Key: インテグレーション環境の公開キーです。pk_test_ で始まります。

Test Secret Key: インテグレーション環境の秘密キーです。sk_test_ で始まり、ブラウザと共有されることはありません。

Live Public Key: 本番環境の公開キーです。pk_live_ で始まります。

Live Secret Key: 本番環境の秘密キーです。sk_live_ で始まり、ブラウザと共有されることはありません。

保存された秘密キーは再表示されません。入力欄は空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ、新しい値を入力してください。保存済みの秘密キーを削除するには、入力欄の下にある Clear the saved key on save にチェックを入れ、Save をクリックします。

決済方法

カードは常に提供されます。銀行振込、代理店、ウォレット、Cuotéalo には Culqi Orders API が必要で、この拡張機能では提供されません。

Yape: Offer Yape in the Culqi popup をオンにすると、Culqi のウィンドウでカードの横に Yape が表示されます。デフォルト：オン。

注文

OpenCart は Confirm Order のステップで、ステータスのない注文（欠落注文）を作成します。注文にステータスが付与されるのは、Culqi が請求を確認した後だけです。以下の各フィールドには、貴店の OpenCart の注文ステータスが表示されます。

Order Status After Payment: Culqi が請求を確認し、その金額と通貨が注文と一致しています。デフォルト：Processing。

On Hold (Review) Status: Culqi が注文と一致しない金額または通貨で請求した、または支払いの捕捉（キャプチャ）ができなかった場合に使われます。メモには、CulqiPanel で確認すべき内容が記載されます。デフォルト：Pending（OpenCart には On hold ステータスがないため）。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

Refunded Status: 注文ページから支払いが全額返金された場合に設定されます。一部返金ではメモが追加されるだけです。デフォルト：Refunded。

詳細設定

Debug log: API リクエストと決済手順を、OpenCart のログフォルダー（storage/logs）にある culqi_p_debug.log.php に記録します。このファイルは Web からは開けず、5 MB に達すると culqi_p_debug.old.log.php に移動されます。カード拒否のコードを含むエラーは常に記録されます。キー、カード情報、顧客の詳細は記録されません。デフォルト：オフ。

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

Delete data on uninstall: オンにすると、拡張機能のアンインストール時にゲートウェイの設定とログが削除されます。Culqi の請求と返金は常に保持されるため、再インストール後も以前に支払われた注文を返金できます。デフォルト：オフ。

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

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

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

チェックアウト

Payment Method のステップで、購入者は決済方法を選択します（デフォルトは Credit/Debit Card or Yape (Culqi)）。Confirm Order のステップでは、購入者に貴店の説明文が表示され、OpenCart はまだステータスのない注文を作成します。購入者が Confirm Order をクリックすると、同じページ上に Culqi Checkout ポップアップが開き、ストア名、注文合計、通貨が表示されます。購入者はそこでカード情報を入力するか、Yape で支払います。Culqi のスクリプトは常に Culqi から読み込まれます。OpenCart 4 では、決済方法ブロックの Choose ボタンを押し、Payment method options ウィンドウで決済方法を選んでから、チェックアウトページ下部の確認ブロックにある Confirm Order をクリックします。ストアが請求先住所を求めない場合（OpenCart 4 の既定）、請求と一緒に送信される顧客情報は、配送先住所と顧客の名前から取得されます。

Culqi は決済データを 1 回限りのトークンに変換し、そのトークンのみが貴店に送信されます。貴店のサーバーは、Culqi Charges API を使用して、注文通貨での注文合計の請求を作成し、即時にキャプチャします。この請求は CulqiPanel に Order、注文番号、購入者のメールアドレスとともに表示されます。注文が支払い済みとしてマークされるのは、Culqi が確認した後だけです。その後、注文は OpenCart の標準的な方法でステータスを取得し、通常の注文メールと在庫更新が行われ、購入者には OpenCart の注文完了ページが表示されます。

銀行が 3-D Secure を要求する場合、購入者には Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. と表示されます。認証が完了すると、請求は自動的に再送信されます。認証が完了しない場合、購入者には The 3-D Secure verification was not completed. Please try again or use another card. と表示されます。

カードが拒否された場合、購入者には Payment failed: の後に Culqi からのメッセージが表示され、同じステップで別のカードを使って再試行できます。Culqi から応答がない場合、購入者には We could not confirm your payment with Culqi. Please check your email or contact us before trying again. と表示されます。これらの場合、注文はステータスなしのままとなり、注文履歴のメモに試行が記録されます。購入者が Culqi のウィンドウを閉じた場合、請求は行われず、Confirm Order ボタンを再度クリックできます。これらのいずれの場合も、カートは保持されます。

注文が二重に請求されることはありません。同じ注文の支払いが処理中に購入者が再送信すると、This order is already being paid. Please wait a moment and check your email before trying again. と表示されます。Culqi が代金を受け取ったものの注文ステータスを設定できなかった場合、購入者には Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. と表示されます。請求は保持され、同じカートでの次の試行は、新たな請求を行わずにそこから注文ステータスを設定します。カートの支払いは 1 回だけです。同じカートの別の注文（OpenCart 3 は Confirm Order のステップが表示されるたびに新しい注文を作成します）がすでに支払い済みの場合、購入者は成功ページに進み、再び請求されることはありません。OpenCart 4 は決済用に 1 つの注文を保持して更新するため、カードが拒否された後も、購入者は同じ注文で支払います。

OpenCart 4 は、成功ページが表示されるまで注文をチェックアウトに保持します。その間に、ストア側で注文が閉じられた場合（たとえばキャンセルまたは返金された場合）、または注文がすでに支払い済みで、その後カートが変更された場合（商品や数量が異なる場合）、Confirm Order をクリックすると購入者はチェックアウトに戻され、そのカートの新しい注文と独自の決済が作成されます。支払い済みで閉じられた注文は、もはやカートを保持しません。

この拡張機能は、1 回限りのカードおよび Yape の決済のみを受け付け、即時にキャプチャします。銀行アプリ、代理店、ウォレット、Cuotéalo には対応しておらず、保存済みカード、サブスクリプション、分割払い、Culqi のウェブフック、個別のオーソリとキャプチャもサポートしていません。

注文と返金

注文ステータス

No status (missing order): 購入者がまだ支払っていない、カードが拒否された、または Culqi から応答がなかった場合です。Sales > Orders では、Order Status フィルターを Missing Orders に設定した場合にのみ、このような注文が表示されます。注文履歴のメモには、失敗した試行が記録されます。

Order Status After Payment (default Processing): 請求が確認され、注文と一致しています。メモには Culqi payment successful、モード（テストまたはライブ）、使用した場合は 3-D Secure、そして Culqi の請求 ID（chr_...）が表示されます。

On Hold (Review) Status (default Pending): Culqi が、注文と一致しない金額または通貨の請求を報告した、またはオーソリのみでキャプチャされていない支払いがあったことを示します。メモにその理由と請求 ID が表示されます。CulqiPanel で請求を確認し、その後、注文を処理するか支払いを返金してください。

Refunded Status (default Refunded): 支払いが拡張機能を通じて全額返金されたことを示します。

メモは、購入者には表示されない注文の History のエントリです。

VibeFox Culqi Payment タブ

Sales > Orders で、Culqi で支払われた注文を開きます。注文ページの下部、History と Additional の隣に表示される VibeFox Culqi Payment タブには、テスト支払いには Test ラベル付きの Charge ID、請求された Amount（使用した場合は 3-D Secure を含む）、保留中の注文の Review のヒント、Paid / refunded の金額、返金フォーム、返金履歴、注文の Culqi notes が表示されます。このタブは、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

VibeFox Culqi Payment タブで Amount を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて Reason (optional) も入力し、Refund via Culqi をクリックします。Refund this amount through Culqi? This cannot be undone. という確認に同意してください。全額返金と一部返金に対応しています。拡張機能を変更する権限が必要です（System > Users > User Groups で設定します）。返金は、Culqi が請求した金額と通貨で行われます。そのため、金額の不一致が発生した後は、注文合計ではなく、購入者が実際に支払った金額までを返金できます。返金は、支払いが行われたモード（テストまたはライブ）のキーで送信されます。その後にモードを切り替えていても同様です。したがって、そのモードの秘密キーを設定しておく必要があります。Culqi が返金を受け付けない場合、タブにエラーが表示され、返金は記録されません。返金が成功すると、Culqi の返金 ID、金額、入力した理由とともに、返金履歴とメモに追加されます。全額返金の場合、購入者に通知せず、商品も在庫に戻さずに、注文は Refunded Status に設定されます（手動でステータスを変更するのと同じです）。一部返金では、ステータスは変わりません。

Sales > Returns での商品返品では、Culqi を通じて返金されることはありません。CulqiPanel で行った返金は、OpenCart には同期されません。必要に応じて注文を手動で更新してください。

ライセンスキー

この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Culqi Payment は、Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit で、設定の上にある最初のブロックです。License key にキーを貼り付け、Activate をクリックします。その後、このブロックにはキーがマスクされて表示され、ステータス（例：ライセンスの有効期限日と貴店のドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: opencart-payment-culqi の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

Culqi がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの両方のキーが設定されていること（テストモードでは Test Public Key と Test Secret Key、ライブモードでは Live Public Key と Live Secret Key）、そして購入者が PEN または USD で支払うことを確認してください。キーが不足している場合、設定ページに警告が表示されます。また、支払い住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

支払いは完了したが、注文がステータスなしのまま: この拡張機能はウェブフックを使用しません。請求は、Culqi から貴店のサーバーへの応答によってのみ確認されます。Culqi が時間内に応答しなかった場合、注文には Culqi did not confirm the charge のメモが付きます。CulqiPanel で、この注文の請求を探してください。購入者が注文を完了できなかったというメッセージを見た場合、同じ購入者セッションでの次の支払い試行は、再請求することなくステータスを設定します。

支払い後、注文が審査ステータスになっている: VibeFox Culqi Payment タブのメモを読んでください。請求された金額または通貨が注文と異なっていたか、支払いがキャプチャされていませんでした。CulqiPanel で請求を確認し、その後、注文を処理するか支払いを返金してください。

キーが保存されない: エラーには、その入力欄は接頭辞（例：sk_live_）で始まる必要があると表示されます。各入力欄は、その種類とモードに対応するキーのみを受け付けます：pk_test_、sk_test_、pk_live_、sk_live_。

購入者に Payment gateway misconfiguration. Please contact the store owner. と表示される: 現在のモードのキーが不足しているか、Culqi が秘密キーを拒否しました。設定でキーを確認してください。

購入者に Payment token is invalid. Please try again. と表示される: Culqi のウィンドウからのトークンは別のモードに属しています。例えば、チェックアウトページが開いている間に Test Mode を切り替えた後です。購入者はページを再読み込みして、もう一度支払う必要があります。

Culqi のウィンドウが開かない: 購入者には The Culqi payment window could not be loaded. Please reload the page and try again. と表示されます。チェックアウトページで js.culqi.com と 3ds.culqi.com のスクリプトがブロックされていないか確認してください。キャッシュや最適化の拡張機能によってブロックされている場合があります。

購入者に Security check failed. Please reload the page and try again. と表示される: チェックアウトページが別のセッションで開かれていました。ページを再読み込みすれば解決します。

購入者に This payment method is not available. と表示される: チェックアウトのセッションに Culqi の注文がもうないか、その間に決済方法がオフにされました。購入者はチェックアウトを再読み込みします。

カードが拒否され、理由を知りたい: 注文のメモ、または拡張機能ページの Log フィールドを確認してください。拒否は、Debug log がオフであっても、Culqi の拒否コードとともに記録されます。

タブに返金フォームがない: タブに理由が表示されます。支払いが全額返金済み、ユーザーグループに拡張機能を変更する権限がない、または決済モードの秘密キーがない、のいずれかです。

キーに関するメッセージで返金が失敗する: 支払いはテストまたはライブモードで行われましたが、そのモードの秘密キーが設定されていません。キーを入力して再試行してください。

アンインストール

Extensions > Extensions に進み、タイプとして Payments を選択し、VibeFox Culqi Payment の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します。具体的には、Enable/Disable、Sort Order、Geo Zone、Total、そして Orders セクションの注文ステータスです。これらは再インストール時にデフォルトに戻ります。Delete data on uninstall がオンの場合、その他のゲートウェイ設定（タイトル、説明、テストモード、キー、Yape、ログ記録）とログも削除されます。オフの場合は、後で再インストールするために保持されます。Culqi の請求と返金は常に保持されるため、再インストール後も以前に支払われた注文を返金できます。既存の注文は、支払いのメモを保持します。

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

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