VibeFox Culqi for WooCommerce — ヘルプ

要件

WordPress: 5.8 以降。

WooCommerce: 6.0 以降。インストールされ、有効化されている必要があります。WooCommerce がないと、プラグインは有効化できません。

PHP: 8.0 以降。

ストアの通貨: ペルー・ソル（PEN）または米ドル（USD）。Culqi はそれ以外の通貨に対応していないため、ストアの通貨が異なる場合、この支払い方法はチェックアウトで非表示になります。

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

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

インストール

1. WordPress で Plugins > Add New > Upload Plugin を開き、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_culqi_payment フォルダーを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。

3. 設定を開きます: WooCommerce > Settings > Payments > Culqi > Manage。または、プラグインページでプラグイン名の下にある Settings をクリックします。

4. ページ上部のライセンス欄に VibeFox ライセンスキーを入力し、Activate をクリックします。

5. 統合キーを貼り付けます。実際の支払いを受け付ける場合は、本番キーも貼り付けます（「設定」を参照）。

6. Enable/Disable をオンにします。テスト中は Test Mode をオンのままにし、実際の支払いを受け付けるときはチェックを外します。

7. ストアの通貨が PEN または USD であることを確認します。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Culqi。テストモードがオンの間、ページにはフィールドの上に Test mode is active: the integration keys are used and no real money is charged. と表示されます。ゲートウェイが有効なのに現在のモードのキーが未設定の場合や、ストアの通貨が Culqi に対応していない場合は、警告が表示されます。どちらの場合も、この支払い方法はチェックアウトで非表示になります。支払い方法の一覧では、現在のモードの 2 つのキーが両方設定されるまで、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 にあります。テストモードではテストキーのみ、本番モードでは本番キーのみが使用されます。各キーは、そのフィールドのプレフィックスで始まっている必要があります。プレフィックスが正しくないキーは保存されず、ページにエラーが表示されて以前の値が保持されます。

Test Mode: Use the Culqi integration (test) environment。オンの場合、テストキー（pk_test_ / sk_test_）が使用され、実際のお金は請求されません。デフォルト: オン。チェックを外すと、本番キーで実際の支払いを受け付けます。

Test Public Key: 統合環境の公開キー。pk_test_ で始まります。

Test Secret Key: 統合環境の秘密キー。sk_test_ で始まり、ブラウザと共有されることはありません。

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

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

バージョン 1.0 から更新する場合、そのバージョンの単一のキーペアは、プレフィックスに応じてテストまたは本番のフィールドに移されます。更新後にキーを確認してください。

支払い方法

カードは常に利用できます。銀行振込、代理店、ウォレット、Cuotéalo には Culqi Orders API が必要で、このプラグインでは提供されません。

Yape: Offer Yape in the Culqi popup は、Culqi のウィンドウでカードの横に Yape を表示します。デフォルト: オン。

詳細設定

Debug log: Log API requests and payment steps は、詳細を WooCommerce > Status > Logs のソース wcp_culqi_payment に書き込みます。エラーは常に記録されます。キー、カード情報、購入者の詳細は記録されません。デフォルト: オフ。

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted。プラグインを無効化しても何も削除されません。注文に保存された Culqi のデータは常に保持されます。デフォルト: オフ。

チェックアウト

購入者は支払い方法（デフォルトでは Credit/Debit Card or Yape (Culqi)）を選び、注文ボタンをクリックします。同じページに、店舗名、注文合計、通貨を表示した Culqi Checkout ポップアップが開きます。購入者はそこでカード情報を入力するか、Yape で支払います。テストモードがオンの間、支払い方法には TEST MODE: No real charges will be made. と表示されます。

Culqi は決済データを 1 回限りのトークンに変換し、そのトークンとともにチェックアウトがストアに送信されます。ストアのサーバーは、Culqi Charges API を使って、注文通貨での注文合計の請求を作成し、請求の説明に注文番号を入れます。注文が支払い済みになるのは、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. と表示され、もう一度注文できます。

この支払い方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の High-Performance Order Storage（HPOS）に対応しています。

本プラグインは、即時にキャプチャされるカードと Yape による 1 回限りの決済のみに対応しています。PagoEfectivo や CIP コード、銀行アプリ、代理店、ウォレット、Cuotéalo、保存済みカード、サブスクリプション、分割払い、Culqi のウェブフック、オーソリとキャプチャの分離には対応していません。

注文と返金

注文ステータス

Pending payment: 注文は作成されたものの、まだ請求されていないか、Culqi が応答しませんでした。この場合、メモに Culqi did not confirm the charge と記載されます。別の支払いを受け付ける前に、CulqiPanel でこの注文の請求を確認してください。

Processing: 支払いが確認されました（WooCommerce のデフォルト。ダウンロード可能な仮想商品のみの注文は「完了」になります）。注文メモには、Culqi の請求 ID、モード（テストまたは本番）、3-D Secure が使われたかどうかが表示されます。トランザクション ID は Culqi の請求 ID です。

On hold: Culqi が、金額または通貨が注文と一致しない請求、あるいはオーソリされたもののキャプチャされていない支払いを報告しました。注文メモに説明と請求 ID が表示されます。CulqiPanel で請求を確認し、注文を手動で完了するか返金してください。

Failed: カードが拒否されました。注文メモには、理由、拒否コード、請求 ID が表示されます。購入者は別のカードで再度支払えます。

すでに支払い済みの注文や、保留中の注文を含め、すでに Culqi の請求がある注文は、再び請求されることはありません。注文ごとに、同時に処理される支払いリクエストは 1 件のみです。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Culqi をクリックします。全額返金と一部返金に対応しています。返金は、その後モードを切り替えていても、支払いが行われたモード（テストまたは本番）のキーで送信されるため、そのモードの秘密キーが設定されている必要があります。Culqi が返金を受け付けない場合、WooCommerce にエラーが表示され、返金は記録されません。返金に成功すると、Culqi の返金 ID、金額、理由とともに注文メモに追加されます。

CulqiPanel で行った返金は WooCommerce に同期されません。必要に応じて、WooCommerce で Refund via Culqi を使わずに手動で返金を作成してください。

ライセンスキー

本プラグインは、vibefox.net の VibeFox ライセンスキーで動作します。ライセンス欄は WooCommerce > Settings > Payments > Culqi の上部にあります。キーを License key に貼り付けて Activate をクリックします。ライセンス欄には、ライセンスの有効期限やドメインなどのステータスが表示されます。ステータスを再確認するには Check now、別のキーを入力するには Change key、このサイトからキーを削除するには Remove key を使います。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。

1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、そのドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。

有効なキーがない場合、Culqi はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には引き続き支払い方法が (unlicensed — visible to admins only) と表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインページと WooCommerce のページにリマインダーが表示されます。既存の注文には影響せず、返金は引き続き利用できます。

ライセンスの有効期限が切れても、プラグインは動作し続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。

トラブルシューティング

Culqi がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの 2 つのキー（テストモードでは Test Public Key と Test Secret Key、本番モードでは Live Public Key と Live Secret Key）が設定されていること、ストアの通貨が PEN または USD であることを確認してください。これらのいずれの場合も、設定ページに警告が表示されます。

支払いは完了したが、注文が Pending payment のまま: 本プラグインはウェブフックを使用しません。請求は、Culqi からサーバーへの応答でのみ確認されます。Culqi が時間内に応答しなかった場合、注文メモに Culqi did not confirm the charge と記載されます。CulqiPanel でこの注文の請求を探し、存在する場合は注文を手動で完了してください。

支払い後に注文が 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 のスクリプトが、最適化プラグインなどによってチェックアウトページでブロックされていないか確認してください。

購入者に This order is already being paid と表示される: 同じ注文に対する別の支払いリクエストが同時に実行されていました。購入者は少し待ち、再試行する前にメールを確認してください。

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

ライセンス欄にエラーが表示される: 欄内のメッセージに従ってください。たとえば、キーがすでに別のドメインで使われている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックします。サイトのアドレスが変わった場合は、Check now をクリックして新しいドメインでキーを有効化します。ライセンスサーバーに接続できない場合、プラグインは最後に確認されたステータスで動作し続けます。

開発者向けに、プラグインのドキュメントには culqi_p_supported_currencies、culqi_p_charge_data、culqi_p_icon、culqi_p_lock_timeout の各フィルターが記載されています。

アンインストール

プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除します。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイの設定とログは、Delete Data on Uninstall がオンだった場合にのみ削除されます。それ以外の場合は、後で再インストールするときのために残ります。既存の注文には、支払いメモとトランザクション ID が残ります。

Culqi は、それぞれの所有者の商標です。本プラグインは Culqi と提携しておらず、Culqi による承認も受けていません。