VibeFox Conekta for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

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

PHP: 8.0 以降。

通貨: ストアの通貨は MXN または USD である必要があります。ほかの通貨では、この決済方法は表示されません。

Conekta アカウント: Conekta アカウントの秘密 API キー（テストと本番）と、Conekta ダッシュボードのウェブフック（「設定」を参照）が必要です。使用するのは秘密キーだけです。支払いは Conekta がホストするチェックアウトページで行われるため、公開キーは不要です。

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

インストール

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

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

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

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

5. テストと本番の秘密キーを入力し、モードを選択して、Conekta ダッシュボードでウェブフックを追加します（「設定」を参照）。

6. Enable / Disable をオンにして保存します。テストモードで支払いをテストしてから、Test mode のチェックを外します。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Conekta。Conekta が有効なのに現在のモードの秘密キーが空の場合（この場合、決済方法はチェックアウトで非表示になります）や、ストア通貨が MXN または USD ではない場合、ページは入力欄の上に警告を表示します。テストモードがオンのときは、Test mode is on: payments are simulated with the test private key. と表示されます。現在のモードのキーがないまま有効なゲートウェイを保存すると、キーの入力を求めるエラーメッセージが表示されます。

一般

Enable / Disable: Enable Conekta payments で決済方法を有効または無効にします。既定値: オフ。

Title: チェックアウトで購入者に表示される決済方法の名称。既定値: Conekta。

Description: チェックアウトで決済方法の下に表示されるテキスト。既定値: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.

Payment methods: Conekta の支払いページで提供される方法。既定値: カード、現金、銀行振込。現金、SPEI、BNPL は MXN の注文でのみ利用できます（USD の注文ではカードのみ）。また、Conekta アカウントで有効にしておく必要があります。何も選択されていない場合は、カードが使用されます。

Credit / debit card: カード決済。

Cash (OXXO and other stores): 購入者は参照番号を受け取り、店舗で現金を支払います。

Bank transfer (SPEI): 購入者は参照番号を受け取り、銀行振込で支払います。

Buy now, pay later (BNPL): Conekta アカウントで有効になっている場合、BNPL オプションによる支払い。

API キー

Conekta ダッシュボードの Developers > API keys から秘密キーをコピーします。テストと本番のキーは別物です。

Test mode: Enable test mode はテスト用の秘密キーを使用します。実際の料金は請求されず、チェックアウトに TEST MODE バッジが表示されます。返金は常に、支払いが行われたモードのキーを使用します。既定値: オン。

Test private key: Conekta アカウントのテストモードの秘密 API キー。

Live private key: Conekta アカウントの本番モードの秘密 API キー。秘密にしてください。

各 Conekta 注文は自身のモードを記憶します。通知と返金では、対応するキーが使用されます。古いテスト注文がまだ開いている間は、両方のキーを入力したままにしてください。

ウェブフック

ウェブフックは、購入者が Conekta のページを離れた後に行われた支払い（例: OXXO または SPEI の支払い）を貴店に通知します。Conekta ダッシュボードで Developers > Webhooks に移動し、このセクションに表示される URL をテストモードと本番モードの両方に追加します。URL の形式は次のとおりです: https://your-site/wc-api/webhook_wc_conekta/。

次のイベントを選択します:

order.paid: 注文が支払われました。

order.pending_payment: 注文は支払いを待っています（例: OXXO または SPEI の参照番号が発行されたとき）。

order.declined: 支払いが拒否されました。

order.expired: チェックアウトまたは支払い参照番号の有効期限が切れました。

order.canceled: Conekta の注文がキャンセルされました。

order.refunded: 支払いが返金されました（例: Conekta ダッシュボードで）。

order.charged_back: 購入者が支払いに異議を申し立てました（チャージバック）。プラグインは注文にメモを追加します。

ウェブフックの本文は、どの Conekta 注文が変更されたかをプラグインに伝えるだけです。すべての通知は、そのモードの秘密キーを使って Conekta API から注文を読み直すことで検証されます。ウェブフックの Digest 署名ヘッダーは使用されません。この店舗がその注文のために作成したものではない Conekta 注文に関する通知は、受領されて無視されます。ウェブフックがない場合、注文が確定するのは、購入者が支払い後に貴店に戻ったときか、同じ注文の次の支払い試行時だけです。

詳細設定

Debug log: Log API calls and notifications を有効にすると、詳細が WooCommerce > Status > Logs に書き込まれます（ソース: wcp_conekta_gateway）。エラーは常に記録されます。ログには API キーや顧客の連絡先情報が含まれることはありません。既定値: オフ。

Delete data on uninstall: Remove the settings, Conekta order references and logs when the plugin is deleted。既定値: オフ。

チェックアウト

購入者は決済方法（既定では Conekta）を選び、注文を確定します。プラグインは、注文金額について注文通貨で Conekta の注文を作成し、注文商品、送料、税金、割引を含めたうえで、購入者を Conekta がホストするチェックアウトページに移動させます。購入者はそこで、許可された方法のいずれかで支払います。

支払い後、購入者は貴店に戻ります。注文が支払い済みになるのは、Conekta が確認した後だけです。プラグインは、ウェブフックが届いたときと購入者が戻ったときに、Conekta API から注文を読み取ります。支払いをまだ確認できない場合、注文受付ページには We are confirming your payment with Conekta. The order will be updated automatically — please do not pay again. と表示されます。購入者が OXXO または SPEI を選び、支払い参照番号を受け取った場合、注文は「保留中」になり、ページには Your Conekta payment reference has been issued. The order will be confirmed as soon as the payment is received. と表示されます。

支払いが拒否された場合、注文は「失敗」としてマークされ、購入者は Pay for order ページに戻ります。そこには The Conekta payment was not completed. Please try again or choose another payment method. と表示されます。チェックアウトの有効期限が切れた場合やキャンセルされた場合、購入者には The Conekta payment has expired or was cancelled. Please place the order again. と表示されます。購入者が注文を再度支払うとき、同じ金額の開いている Conekta チェックアウトがあれば再利用されます。それ以外の場合は、新しいチェックアウトを作成する前に、以前のものが Conekta でキャンセルされます。そのため、古いリンクで二重に支払われることはありません。以前のチェックアウトがすでに支払い済みだった場合は、再請求されるのではなく、その支払いが記録されます。

Conekta が支払いを開始できない場合、購入者には短いメッセージが表示されます（例: The payment could not be started. Please try again in a moment or choose another payment method.）。技術的な理由はログに書き込まれます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce High-Performance Order Storage (HPOS) に対応しています。テキストはスペイン語（メキシコ）に翻訳されています。

プラグインが支払いを受け付けるのは Conekta のページでのみです。チェックアウトページにカードフォームはなく、保存済みカード、サブスクリプション、事前承認とキャプチャ、月払い分割（MSI）には対応していません。

注文と返金

注文ステータス

Pending payment: 購入者は Conekta に移動しましたが、まだ支払っていません。注文メモには Conekta の注文とモードが表示されます。

Processing: Conekta が同じ金額と通貨で支払いを確認しました（ダウンロード可能な仮想商品のみの注文は、WooCommerce の既定どおり「完了」になります）。注文メモには、支払い方法（例: カードブランドと下 4 桁、OXXO / 現金、または SPEI 銀行振込）、Conekta の注文、および請求が表示されます。注文のトランザクション ID は、Conekta の請求 ID（charge ID）です。

On hold, waiting for OXXO or SPEI: 購入者は支払い参照番号を受け取りました。Conekta が支払いを通知すると、注文は「処理中」になります。

On hold after payment: Conekta から受け取った金額または通貨が注文と一致しない、ストアが本番モードの間にテストモードの支払いが届いた（実際の料金は回収されていません）、またはすでにキャンセルされた注文に対して支払いが届いた。注文メモにその内容が説明されています。支払いを確認してから、注文を完了するか返金してください。Conekta で事前承認だけされた注文も「保留中」になり、Conekta ダッシュボードでキャプチャまたは取り消しを行うようメモが表示されます。

Failed: 支払いが拒否されました。メモに理由が表示されます。購入者は再度支払うことができます。

Cancelled: 現在の Conekta チェックアウトの有効期限が切れたか、キャンセルされました。

支払い済みまたは返金済みの注文が格下げされたり再度開かれたりすることはありません。支払い済みの注文に対して別の Conekta 支払いが届いた場合、WARNING メモが表示され、Conekta ダッシュボードで返金するよう求められます。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Conekta をクリックします（ボタンには決済方法のタイトルが表示されます）。全額返金と一部返金に対応しています。返金は、支払いを含む Conekta 注文に対して行われ、支払いが行われたモードのキーを使用します。そのため、そのキーを設定しておく必要があります。Conekta が返金を受け付けない場合、WooCommerce にエラーが表示され、返金は記録されません。成功した返金は、金額、モード、Conekta 注文、返金 ID、理由とともに注文メモに追加されます。

Conekta ダッシュボードで行われた返金はウェブフックで届き、Conekta と WooCommerce で返金された金額を示すメモとして追加されます。これらは WooCommerce の返金として自動的に記録されることはありません。Refund via Conekta を使わずに手動で記録してください。Conekta が報告したチャージバックも、メモとして追加されます。

ライセンスキー

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

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

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

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

トラブルシューティング

Conekta がチェックアウトに表示されない: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードの秘密キーが入力されていること（テストモードでは Test private key、本番モードでは Live private key）、そしてストア通貨が MXN または USD であることを確認してください。設定ページには、これらの各条件について警告が表示されます。

支払いは完了しているのに、注文が Pending payment のまま: ウェブフックが動作していません。Conekta ダッシュボードで、使用しているモード（テストまたは本番）のウェブフックが存在すること、その URL が設定に表示されたものとまったく同じであること、そしてイベントが選択されていることを確認してください。そのモードの秘密キーが設定されていることも確認してください。すべての通知はそのキーで検証されるためです。注文は、購入者が貴店に戻ったとき、または同じ注文の支払いを再度試みたときにも確定します。

ウェブフックが Temporarily unavailable と応答する: Conekta API に接続できなかった、注文のモードの秘密キーがない、または注文が別のリクエストで処理中だった可能性があります。Conekta はウェブフックを再送します。

ウェブフックが Verification failed、Invalid payload、または Invalid order id と応答する: Conekta API が注文を確認できなかったか、通知が有効な Conekta 注文イベントではありませんでした。

ウェブフックが Ignored と応答する: 通知は、この店舗がその注文のために作成していない Conekta 注文に関するものです（例: 別の店舗、または同じアカウントの支払いリンク）。あるいは、注文以外のオブジェクトに関するものです。

購入者に We could not check the status of your previous payment attempt と表示される: その注文の以前の Conekta チェックアウトを読み取れなかったため、二重払いを防ぐために新しいものは作成されません。しばらくしてから再試行してください。

購入者に Payment gateway is not configured と表示される: 現在のモードの秘密キーがありません。

注文が On hold になっている: 注文メモを確認してください。購入者がまだ OXXO または SPEI の参照番号を支払っていない、金額または通貨が一致しなかった、またはストアが本番モードの間にテストモードの支払いが届いた、のいずれかです。

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

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

開発者向け: readme には、通貨リストのためのフィルター wc_ckt_supported_currencies が記載されています。

アンインストール

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

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