VibeFox Conekta for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールできません。

通貨: カートの通貨は MXN または USD である必要があります。それ以外の通貨では、その支払い方法は表示されません。

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

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

インストール

1. バックオフィスで Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

2. アップロードが完了したら Configure をクリックするか、後でモジュール一覧から VibeFox Conekta Gateway を探して Configure をクリックします。

3. Configure ページ上部のライセンスブロックの License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。

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

5. Enable / Disable を有効にして Save をクリックします。テストモードで支払いをテストしてから、Test mode を無効にします。

インストール時に、モジュールは 2 つの注文ステータス Awaiting Conekta payment と Conekta payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。これらは Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Conekta Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。フィールドの上部では、Conekta が有効になっているのに現在のモードのプライベートキーが空の場合（この場合、チェックアウトでは支払い方法が非表示になります）や、ストアのデフォルト通貨が MXN でも USD でもない場合に警告が表示されます。テストモードがオンのときは、テストモードはオンです：支払いはテスト用プライベートキーでシミュレートされます。 と表示されます。現在のモードのキーを入力せずに有効なゲートウェイを保存すると、そのキーの入力を求める警告が表示されます。

Conekta

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 の支払いページで提供される方法です。デフォルト: card, cash and bank transfer。現金払い、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: テスト用プライベートキーを使用します。実際の料金は請求されず、チェックアウトでは支払い方法の下に TEST MODE バッジと 実際の請求は行われません。 という表示が出ます。返金は常に、支払いが行われたモードのキーを使用します。デフォルト: オン。

Test private key: Conekta アカウントのテストモードのプライベート API キーです。

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

保存済みのキーは再び表示されません。フィールドは空のままで、保存済み — 変更しない場合は空のままにしてください。 と表示されます。値を変更する場合にのみ新しい値を入力してください。

Clear saved keys: キーにチェックを入れて Save をクリックすると削除されます。フィールドを空のままにすると、保存済みの値が維持されます。

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

ウェブフック

ウェブフックは、購入者が Conekta のページを離れた後に行われた OXXO や SPEI の支払いなど、支払いに関する情報を貴店に通知します。Conekta ダッシュボードで Developers > Webhooks に移動し、API keys セクションの Webhook フィールドに表示された URL を、テストモード用と本番モード用の両方に追加します。フレンドリー URL を使用している場合、その形式は https://your-shop/module/wcp_conekta_gateway/webhook のようになり、/en/ などの言語コードが付く場合もあります。URL は設定に表示されたとおりに正確にコピーしてください。

次のイベントを選択します（設定にも一覧で表示されています）：

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: API 呼び出しと通知を、モジュールフォルダ内の logs/wc_ckt_debug.log.php に記録します。このファイルは Web からは開けません。エラーと警告は、このスイッチがオフでも常に記録されます。ログには API キーや購入者の連絡先情報は含まれません。デフォルト: オフ。

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

Delete data on uninstall: オンにすると、モジュールのアンインストール時に設定とログが削除されます。Conekta の取引と返金、注文ステータス、注文は常に保持されるため、再インストール後も古い注文を確認して返金できます。デフォルト: オフ。

チェックアウト

支払いステップで、購入者は支払い方法（デフォルトは Conekta）を選んで確定します。モジュールは、カートの合計金額についてカートの通貨で Conekta の注文を作成します。この注文には商品、ギフトラッピング、割引、税金、送料が含まれ、購入者は Conekta がホストするチェックアウトページに移動します。Conekta のページでは、支払いは Order # とカート番号として表示されます。そこで購入者は許可された方法のいずれかで支払います。この時点ではまだ注文は存在しません。

支払い後、購入者は貴店に戻ります。注文が支払い済みとしてマークされるのは、Conekta が確認した後だけです。モジュールは、ウェブフックが届いたときと購入者が戻ったときに、Conekta API から注文を読み取ります。その後注文が作成され、購入者には標準の注文確認ページが表示されます。そこには Conekta での支払いを受け付けました。 と表示されます。購入者が OXXO または SPEI を選び、支払い参照番号を受け取った場合、注文は Awaiting Conekta payment として作成され、ページには Conekta の支払い参照番号が発行されました。支払いを受領次第、注文を確定します。 と表示されます。参照番号がその後期限切れになった場合、注文はキャンセルされ、その確認ページには Conekta での支払いは完了しませんでした。この注文についてお問い合わせください。 と表示されます。

購入者が戻った時点でまだ支払いを確認できない場合は、支払いの確認ページに Conekta での支払いを確認しています。注文は自動的に更新されます。再度お支払いいただく必要はありません。 と表示され、Check again ボタンが表示されます。ウェブフックが届くと、すぐに注文が作成されます。

支払いが拒否された場合、注文は作成されず、購入者は Conekta での支払いは完了しませんでした。もう一度お試しいただくか、別の支払い方法をお選びください。 と表示されたチェックアウトに戻ります。チェックアウトの有効期限が切れたか、キャンセルされた場合のメッセージは Conekta での支払いの有効期限が切れたか、キャンセルされました。もう一度お試しください。 です。カートは保持されます。購入者が再度支払うときは、同じ金額の開いている Conekta チェックアウトが再利用されます。そうでない場合は、新しいものを作成する前に、以前のチェックアウトが Conekta でキャンセルされるため、古いリンクで二重に支払われることはありません。以前のチェックアウトがすでに支払い済みであった場合は、再度請求するのではなく注文が作成されます。

Conekta が支払いを開始できない場合、購入者はチェックアウトに留まり、短いメッセージ（例：支払いを開始できませんでした。しばらくしてから再度お試しいただくか、別の支払い方法をお選びください。）が表示されます。最低金額などの Conekta からの検証メッセージは、Conekta が送信したとおりに表示されます。技術的な理由はログに記録されます。

ウェブフックは、店舗がメンテナンスモードのときも動作し、店舗の国による制限でブロックされることはありません。

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

注文と返金

注文ステータス

No order yet: 購入者は Conekta に移動したものの、支払っていない、支払いが拒否された、または Conekta がまだ支払いを確認していない状態です。カートだけが存在します。

Payment accepted: Conekta が同じ金額と通貨で支払いを確認しました。支払いは Conekta の請求 ID を取引 ID として記録され、メモには支払い方法（例：カードブランドと末尾 4 桁、OXXO / 現金、または SPEI 振込）、Conekta の注文、請求が表示されます。

Awaiting Conekta payment: 購入者が OXXO または SPEI の支払い参照番号を受け取りました。Conekta が支払いを報告すると、注文は Payment accepted になります。

Conekta payment on hold: Conekta から受け取った金額または通貨がカートと一致しません（例：支払い開始後にカートが変更された）。店舗が本番モードのときにテストモードの支払いが届いた（実際の料金は回収されていない）。または、すでにキャンセルされた注文に対して支払いが届いた。メモにその理由が説明され、支払いは実際に支払われた金額で記録されます。注文を確認したうえで、注文を処理するか支払いを返金してください。Conekta で事前承認のみの注文も同様に保留され、Conekta ダッシュボードでキャプチャまたは取消を行うよう促すメモが付きます。

Canceled: 保留中の注文の OXXO または SPEI 参照番号の有効期限が切れたか、その Conekta 注文がキャンセルされました。

Refunded: モジュールを通じて支払いが全額返金されました。

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

Conekta 支払いブロック

注文ページには Conekta payment ブロックが表示され、Conekta の注文、請求、支払いステータス、支払い済み金額と返金済み金額、テスト支払い用の Test mode バッジ、返金履歴、注文の Conekta notes が含まれます。

返金

Conekta payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Conekta をクリックします。この金額を Conekta 経由で返金しますか？この操作は取り消せません。 という確認に応じてください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。返金は、Conekta が実際に請求した金額と通貨に限られます。そのため、金額に不一致があった場合は、注文の合計ではなく、購入者が支払った金額まで返金できます。返金は支払いを含む Conekta の注文に対して行われ、支払いが行われたモードのキーを使用します。そのため、そのキーが設定されている必要があります。Conekta が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。返金が成功すると、金額、モード、Conekta の注文、返金 ID、理由とともに、返金履歴とメモに追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。返金は、Conekta が支払いを報告した後に利用できます。

モジュールはクレジットメモを作成しません。注文ページの PrestaShop 標準の返金ボタンでは、Conekta を経由して返金されることはありません。

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

ライセンスキー

モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox Conekta Gateway のライセンスブロックは、Modules > Module Manager > VibeFox Conekta Gateway > Configure ページで設定より上にある最初のブロックです。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-conekta の行と、vibefox.net アカウントを開く「アカウントでライセンスとドメインを管理」リンクがあります。キーを変更できるのは、このモジュールの Configure 権限を持つスタッフだけです。ブロックのテキストはバックオフィスの言語に従います（英語とロシア語を含みます）。

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

1 つのキーは 1 つのドメインでのみ使用できます。マルチストア構成の場合も、メインショップのドメインが対象です。ショップからキーを削除しても、ドメイン枠は解放されません。vibefox.net アカウントで枠を解放してください。

有効なキーがない場合、Conekta はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には この支払い方法は利用できません。別の方法をお選びください。 と表示されます。PrestaShop のストアフロントは、あなたがバックオフィスにログインしていることを認識しないため、支払い方法はあなたにも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文は影響を受けません。すでに開始された支払いは引き続き確認され、返金も機能します。

ライセンスが期限切れになっても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、バックオフィスで作業している間に自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに Conekta が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードのプライベートキーが入力されていること（テストモードでは Test private key、本番モードでは Live private key）、カートの通貨が MXN または USD であることを確認してください。キーが不足している場合や、ストアの通貨がサポートされていない場合、設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているか確認してください。

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

ウェブフックの応答が Temporarily unavailable: Conekta API に接続できなかった、注文のモードのプライベートキーが不足している、カートが別のリクエストで処理中だった、または注文を作成できなかった（例：モジュールが無効になっている）ことを示します。Conekta はウェブフックを再試行します。理由は Log フィールドで確認してください。

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

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

ブラウザでウェブフックの URL に Method not allowed と表示される: これは正常です。この URL は Conekta からのリクエストのみを受け付けます。

購入者に「以前の支払い試行の状態を確認できませんでした」と表示される: そのカートの以前の Conekta チェックアウトを読み取れなかったため、二重支払いを避けるために新しいチェックアウトは作成されません。しばらくしてから再度お試しください。

購入者に「支払いゲートウェイが設定されていません」と表示される: 現在のモードのプライベートキーが不足しています。

購入者に「支払いの検証に失敗しました」と表示される: Conekta からの戻りリンクがカートと一致しませんでした。Conekta ダッシュボードで注文を確認してください。ウェブフックは引き続き実際の支払いを確認します。

注文が Awaiting Conekta payment または Conekta payment on hold になっている: 注文ブロックの Conekta notes を確認してください。購入者がまだ OXXO または SPEI の参照番号を支払っていない、金額または通貨が一致しなかった、店舗が本番モードのときにテストモードの支払いが届いた、または支払いが事前承認のみであるなどの理由が考えられます。

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

開発者向けに、README には次のフック一覧が記載されています：actionWcpConektaSupportedCurrencies、actionWcpConektaOrderRequest、actionWcpConektaAllowedPaymentMethods、actionWcpConektaRefundReason。

アンインストール

Modules > Module Manager に移動し、VibeFox Conekta Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンス状態は常に削除されます。Delete data on uninstall がオンの場合、設定とログが削除されます。オフの場合、後で再インストールできるようにすべての設定が保持されます。Conekta の取引と返金、Awaiting Conekta payment と Conekta payment on hold の注文ステータスは常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いメモと取引 ID を保持します。

Conekta は、それぞれの所有者の商標です。本モジュールは Conekta と提携しておらず、Conekta による承認も受けていません。