VibeFox Culqi for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x。
PHP: 8.0 以降。古い PHP バージョンでは、モジュールはインストールされません。
ショップの通貨: ペルー・ソル（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. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックするか、後でモジュール一覧から VibeFox Culqi Payment を探して Configure をクリックします。
3. Configure ページ上部のライセンスブロックの License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（「ライセンスキー」を参照）。
4. インテグレーションキーを貼り付け、実際の決済を行う場合は本番キーも貼り付けます（「設定」を参照）。
5. Enable/Disable をオンにして Save をクリックします。テスト中は Test Mode をオンのままにし、実際の決済を受け付ける際にオフにします。
6. PEN または USD がショップの有効な通貨であることを確認します。
インストール時に、モジュールは注文ステータス Culqi payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。Payment > Preferences で制限できます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Culqi Payment > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。テストモードがオンの間、フィールドの上に Test mode is active: the integration keys are used and no real money is charged. と表示されます。ゲートウェイが有効なのに現在のモードのキーがない場合や、ショップの通貨のいずれも Culqi でサポートされていない場合には警告が表示されます。どちらの場合も、決済方法は決済ステップで非表示になります。デフォルトの通貨が PEN または USD でない場合、ページには、Culqi はサポートされている通貨のカートに対してのみ提供されると表示されます。
Culqi
Enable/Disable: Enable Culqi Payment Gateway は、決済方法をオンまたはオフにします。デフォルト: オフ。
Title: 決済ステップで購入者に表示される決済方法の名称です。注文にも決済方法名として保存されます。デフォルト: Credit/Debit Card or Yape (Culqi)。必須。
Description: 決済ステップで決済方法の下に表示されるテキストです。デフォルト: Pay securely with your credit/debit card or Yape via Culqi.
API キー
キーは CulqiPanel > Desarrollo > API Keys からコピーします。インテグレーション（テスト）キーは integ-panel.culqi.com、本番キーは mipanel.culqi.com から取得します。テストモードではテストキーのみ、本番モードでは本番キーのみが使用されます。各キーは、そのフィールドのプレフィックスで始まる必要があります。プレフィックスが誤っているキーは保存されません。ページにはエラーが表示されます。例: Live Secret Key must start with sk_live_ — the previous value was kept. 他のフィールドは保存されます。
Test Mode: オンの場合、テストキー（pk_test_ / sk_test_）が使用され、実際の料金は請求されません。デフォルト: オン。本番キーで実際の決済を受け付けるにはオフにします。オンの間、購入者には決済方法の下に 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 saved secret keys: Test Secret Key または Live Secret Key にチェックを入れ、Save をクリックすると削除されます。フィールドが空の場合は、保存済みの値が維持されます。
決済方法
カードは常に提供されます。銀行振込、代理店、ウォレット、Cuotéalo には Culqi Orders API が必要で、本モジュールでは提供されません。
Yape: Offer Yape in the Culqi popup をオンにすると、Culqi のウィンドウでカードの横に Yape が表示されます。デフォルト: オン。
詳細設定
Debug log: API リクエストと決済ステップを、モジュールフォルダ内の logs/culqi_p_debug.log.php に記録します。このファイルはウェブから開くことはできません。エラーは、カードの拒否とそのコードを含めて常に記録されます。キー、カード情報、購入者の詳細は記録されません。デフォルト: オフ。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。
Delete Data on Uninstall: オンの場合、モジュールをアンインストールすると、ゲートウェイ設定、モジュールの Culqi 請求と返金の記録、ログが削除されます。注文ステータスと注文の Culqi データ（支払い、メモ）は常に保持されます。デフォルト: オフ。
決済
決済ステップで購入者は決済方法（デフォルトは Credit/Debit Card or Yape (Culqi)）を選び、注文確定ボタンをクリックします。Culqi Checkout のポップアップが同じページに開き、ショップ名、カートの合計金額、通貨が表示されます。購入者はそこでカード情報を入力するか、Yape で支払います。Culqi のスクリプトは決済ページでのみ読み込まれます。
Culqi は支払いデータを 1 回限りのトークンに変換し、そのトークンがショップに送信されます。サーバーは Culqi Charges API で、カートの通貨によるカート合計の請求を作成し、すぐに確定（キャプチャ）します。請求は CulqiPanel に Cart とカート番号、購入者のメールアドレスとともに表示されます。この時点までは注文は存在しません。Culqi が確認した後にのみ、注文は支払い済みとしてマークされます。注文は、Culqi が成功した請求を応答した時点で作成され、購入者には標準の注文確認ページが表示されます。
銀行が 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. と表示されます。
カードが拒否された場合、購入者には Culqi からのメッセージが表示されます（例: Payment failed: の後に理由）。購入者は別のカードで再試行できます。Culqi が応答しない場合、購入者には We could not confirm your payment with Culqi. Please check your email or contact us before trying again. と表示されます。購入者が Culqi のウィンドウを閉じた場合は、請求は行われず、購入者には The payment window was closed before the payment was completed. と表示され、注文をやり直すことができます。これらのいずれの場合も、カートは保持されます。注文がまだ存在しないため、失敗した試行はモジュールのログに記録されます。
カートが二重に請求されることはありません。同じカートの支払いが処理中に購入者が再度送信した場合、購入者には 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. と表示されます。請求は保持され、次の試行では新たな請求なしにその請求から注文が作成されます。
本モジュールは、カードと Yape による 1 回限りの決済のみに対応し、即時にキャプチャします。PagoEfectivo や CIP コード、銀行アプリ、代理店、ウォレット、Cuotéalo、保存済みカード、サブスクリプション、分割払い、Culqi のウェブフック、オーソリとキャプチャの分離には対応していません。
注文と返金
注文ステータス
No order yet: カードが拒否された、購入者が Culqi のウィンドウを閉じた、または Culqi が応答しなかった場合です。カートだけが存在します。詳細はモジュールのログにあります。
Payment accepted: 請求が確認され、カートと一致しています。支払いは Culqi の請求 ID（chr_...）をトランザクション ID として記録され、メモにモード（テストまたは本番）と 3-D Secure の使用有無が表示されます。
Culqi payment on hold: Culqi が、金額または通貨がカートと一致しない請求、または承認されたがキャプチャされていない支払いを報告しました。メモにその内容と請求 ID が表示されます。カートの通貨でキャプチャされた請求は、実際に請求された金額の支払いとして記録されます。CulqiPanel で請求を確認し、注文を処理するか、支払いを返金してください。
Refunded: モジュールを通じて支払いが全額返金されました。
すでに注文があるカートに対して 2 件目の請求が届いた場合、注文は変更されません。メモで、CulqiPanel で請求を確認し、必要に応じて返金するよう案内されます。
Culqi payment ブロック
注文ページには、請求 ID、請求された金額（3-D Secure を使用した場合はその旨）、テスト支払い用の Test バッジ、保留中の注文の確認ヒント、支払い済み金額と返金済み金額、返金履歴を示す Culqi payment ブロックが表示されます。
返金
Culqi payment ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via Culqi をクリックします。Refund this amount through Culqi? This cannot be undone. の確認に応答してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。モジュールへのアクセス権は必要ありません。返金は Culqi が請求した金額と通貨で行われるため、金額の不一致があった場合は、注文合計ではなく、購入者が実際に支払った金額まで返金できます。返金は、支払いが行われたモード（テストまたは本番）のキーで送信されます。その後モードを切り替えていても同様です。そのため、そのモードの秘密キーが設定されている必要があります。Culqi が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。返金に成功すると、Culqi の返金 ID、金額、入力した理由とともに、返金履歴と注文メモに追加されます。全額返金を行うと、注文は Refunded になります。一部返金では、ステータスは変わりません。
本モジュールはクレジットスリップを作成しません。注文ページの標準の PrestaShop の返金ボタンでは、Culqi を通じて返金されません。CulqiPanel で行った返金は PrestaShop に同期されません。必要に応じて注文を手動で更新してください。
ライセンスキー
本モジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Culqi Payment は、Modules > Module Manager > VibeFox Culqi Payment > Configure の最上部、設定の上にあるブロックです。キーを License key に貼り付け、Activate をクリックします。その後、このブロックには、マスクされたキー、ステータス（例：ライセンスの有効期限日とお使いのドメイン）、および次のボタンが表示されます：Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）。その下には Product: presta-payment-culqi という行と、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）。ショップの URL を変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスで動作を続けます。
1 つのキーは 1 つのドメインで使用できます。これはメインショップのドメインを指し、マルチストア構成でも同様です。ショップからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがないと、決済時に Culqi は購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、この決済方法は管理者にも非表示になります。キーを購入する前にモジュールを設定することはできますが、決済時にテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文は影響を受けません。すでに開始された支払いは引き続き確認され、返金も機能します。
ライセンスの有効期限が切れた場合も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面で作業している間に自動的に再確認されます。キーを入力後最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
決済時に Culqi が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの 2 つのキーが設定されていること（テストモードでは Test Public Key と Test Secret Key、本番モードでは Live Public Key と Live Secret Key）、およびカートの通貨が PEN または USD であることを確認してください。キーが不足している場合、設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているか確認してください。
支払いは完了したが注文が作成されなかった: モジュールはウェブフックを使用しません。請求は、Culqi からサーバーへの応答によってのみ確認されます。Culqi が時間内に応答しなかった場合、モジュールのログにカート番号とともに Culqi did not confirm the charge と記録されます。この cart_id を使用して CulqiPanel で請求を検索してください。購入者に注文を完了できなかったとのメッセージが表示された場合、同じカートの次の支払い試行では、再請求なしに注文が作成されます。
支払い後、注文が Culqi payment on hold になる: 注文のメモを確認してください。請求された金額または通貨がカートと異なった、または支払いがキャプチャされなかった可能性があります。CulqiPanel で請求を確認し（ID はメモに記載されています）、注文を処理するか、支払いを返金してください。
キーが保存されない: エラーは、フィールドが 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 order is already being paid と表示される: 同じカートに対する別の支払いリクエストが、ちょうど同時に処理されていました。購入者は、しばらく待ってからメールを確認し、再試行してください。
カードが拒否された理由を知りたい: モジュールページの Log フィールドを確認してください。Debug log がオフでも、拒否は Culqi の拒否コードとともに記録されます。
キーに関するメッセージが表示されて返金に失敗する: 支払いはテストモードまたは本番モードで行われ、そのモードの秘密キーが設定されていません。キーを入力して、再試行してください。
アンインストール
Modules > Module Manager に移動し、VibeFox Culqi Payment の横にあるメニューを開いて、Uninstall を選択します。本モジュールのライセンスキーとライセンスステータスは常に削除されます。Delete Data on Uninstall がオンの場合、ゲートウェイ設定、モジュールの Culqi 請求と返金の記録、ログが削除されます。それ以前に支払い済みの注文は、注文ページから返金できなくなります。オフの場合は、後で再インストールできるようにすべてが保持されます。注文ステータス Culqi payment on hold は常に保持されます。既存の注文は、支払いメモとトランザクション ID を保持します。
Culqi は、その所有者の商標です。本モジュールは Culqi と提携しておらず、Culqi による承認も受けていません。