VibeFox Wompi for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古いバージョンの PHP ではモジュールはインストールされません。

通貨: コロンビア・ペソ（COP）。Wompi Colombia は COP で決済し、COP 以外の通貨のカートでは支払い方法が非表示になります。ストアの既定の通貨が COP でない場合、設定ページに警告が表示されます。

Wompi アカウント: Wompi Colombia の加盟店アカウント。各環境（サンドボックスと本番）には 4 つのキーがあります。公開キー、秘密キー、イベントシークレット、整合性シークレットです。これらは Wompi の加盟店管理画面（comercios.wompi.co）の開発者セクションにあります。Wompi El Salvador と Panama は別の API を使用するため、対応していません。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox Wompi Payment を見つけて Configure をクリックすることもできます。

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

4. Wompi の加盟店管理画面からサンドボックスと本番のキーを貼り付け、Wompi でイベント URL を設定します（設定を参照）。

5. Enable/Disable をオンにして Save をクリックします。サンドボックスモードで支払いをテストしてから、実際の支払いを受け付けるために Sandbox mode をオフにします。

インストール時に、モジュールは 2 つの注文ステータス Awaiting Wompi payment と Wompi payment on hold を作成します。PrestaShop は、その時点で存在する通貨、国、顧客グループに対して新しい支払いモジュールを提供します。Payment > Preferences で COP が許可されていることを確認してください。後から追加した国は、その国の顧客に Wompi が表示される前に、そこでチェックを入れておく必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Wompi Payment > Configure。フィールドのある各セクションには専用の Save ボタンがあり、ページ全体が保存されます。フィールドの上にあるステータスボックスには現在のモード（SANDBOX または PRODUCTION）が表示されます。このモードのキーが不足している場合、ボックスにそのキーが一覧表示され、この環境のすべてのキーが設定されるまで、チェックアウトで支払い方法が非表示になることが示されます。すべてのキーが設定されると、実際の支払いが請求されるかどうかが示されます。保存時には、キーがそのセクションの接頭辞で始まっていない場合や、Wompi が有効なのにキーが不足しているためチェックアウトで非表示になっている場合に、モジュールが警告します。

Wompi

Enable/Disable: Enable Wompi で支払い方法をオンまたはオフにします。既定値：off。

Title: チェックアウトで購入者に表示される支払い方法の名前です。注文にも保存される支払い方法名になります。既定値：Wompi。空欄にするとモジュール名が使われます。

Description: チェックアウトで支払い方法の下に表示されるテキストです。既定値：Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Wompi アカウント

キーは Wompi の加盟店管理画面（comercios.wompi.co）の開発者セクションからコピーします。各環境には、独自の公開キー、秘密キー、イベントシークレット、整合性シークレットがあります。

Sandbox mode: Wompi のサンドボックスを使用します（サンドボックスのキーを使用し、実際のお金は動きません）。キーと Wompi API（sandbox.wompi.co または production.wompi.co）の両方が切り替わります。支払い試行は、行われた環境を保持します。既定値：on。実際の支払いを受け付けるにはオフにします。オンの間、購入者には支払い方法の下に サンドボックスモード：実際の支払いは行われません。 と表示されます。

サンドボックスのキー

Wompi サンドボックスの 4 つのキーです。それぞれ pub_test_、prv_test_、test_events_、test_integrity_ で始まります。

Public key: サンドボックスの公開キー（pub_test_...）。Wompi Web Checkout 上でアカウントを識別します。

Private key: サンドボックスの秘密キー（prv_test_...）。Wompi API からトランザクションを読み取るために使用します。

Events secret: サンドボックスのイベントシークレット（test_events_...）。Wompi イベントの署名を検証します。

Integrity secret: サンドボックスの整合性シークレット（test_integrity_...）。Web Checkout に送信される支払いリクエストに署名します。

本番のキー

Wompi 本番環境の 4 つのキーです。それぞれ pub_prod_、prv_prod_、prod_events_、prod_integrity_ で始まります。

Public key: 本番の公開キー（pub_prod_...）。

Private key: 本番の秘密キー（prv_prod_...）。

Events secret: 本番のイベントシークレット（prod_events_...）。

Integrity secret: 本番の整合性シークレット（prod_integrity_...）。

公開キーは各フィールドに表示されます。保存済みの秘密キーとシークレットは二度と表示されません。フィールドは空のままで、保存済み：そのままにするには空欄のままにしてください。 と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved secrets: いずれかの環境の秘密キーまたはシークレットにチェックを入れて Save をクリックすると削除されます。空欄のフィールドは保存済みの値を保持します。

イベント URL（webhook）

Wompi のイベントは、トランザクションが変更されたことをストアに知らせます。Wompi の加盟店管理画面の開発者セクションで、このセクションに表示されるイベント URL を、サンドボックスと本番の両方に設定します。フレンドリー URL を使用している場合は、https://your-shop/module/wcp_wompi_payment/webhook のような形になり、/es/ のような言語コードが付くこともあります。設定に表示されている URL を正確にコピーしてください。

モジュールは次のイベントを使用します：

その他のイベントには Ignored と応答されます。各イベントは、その環境（サンドボックスまたは本番）のイベントシークレットで検証されます。有効な署名のない webhook は拒否されます。検証の後、その環境の秘密キーを使って Wompi API からトランザクションが読み取られ、そのデータのみが使用されます。イベント URL がない場合、注文は購入者が支払い後にストアに戻ったときにのみ作成されます。

詳細設定

Debug log: 支払いと webhook の動作を、モジュールフォルダ内の logs/wompi_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。このオプションがオフでも、エラーと警告は常に記録されます。キー、シークレット、購入者データは記録されません。既定値：off。

Log: ログのサイズと最新のエントリを表示します。Clear log をクリックするとログが消去されます。

Delete data on uninstall: オンの場合、モジュールをアンインストールするとモジュールの設定とログが削除されます。Wompi の支払い試行とモジュールの注文ステータスは常に残るため、既存の注文は Wompi のデータを保持します。既定値：off。

チェックアウト

支払いの段階で、購入者は支払い方法（既定では Wompi）を選択して確定します。モジュールは独自の参照番号（PS-、カート番号、タイムスタンプ）で支払い試行を作成し、整合性シークレットで署名して、カートの合計金額を COP で表示した状態の Wompi Web Checkout に購入者を移動させます。購入者のメールアドレスと請求先住所の氏名が Wompi に渡されます。この時点ではまだ注文は存在しません。

Wompi のページで購入者は、Wompi アカウントで有効になっている任意の支払い方法で支払います。その後、Wompi は購入者をストアに戻します。注文は、Wompi が確認した後にのみ支払い済みとしてマークされます。署名付きイベントによるか、購入者が戻った時点で Wompi API へのサーバー側リクエストによって確認されます。戻りアドレス内のトランザクション番号自体は信頼されず、試行の環境でそのカートのために作成されたトランザクションのみが受け付けられます。ページの再読み込み時には、トランザクションは最大で 20 秒に 1 回再確認されます。

トランザクションが承認されると注文が作成され、購入者には標準の注文確認ページが表示されます。保留中の支払い（例：PSE、Nequi、現金払い）の場合、ページには Wompi での支払いは確認待ちです（例：PSE、Nequi、現金払い）。Wompi が支払いを確認次第、注文を処理します。 と表示されます。保留状態の注文の場合は Wompi での支払いを受け付け、確認しています。必要な場合はご連絡します。 と表示されます。保留中の支払いがその後拒否された場合、ページには Wompi での支払いは承認されませんでした。お問い合わせください。 と表示されます。取り消された場合は Wompi での支払いは取り消され、この注文はキャンセルされました。お問い合わせください。 と表示されます。

購入者が戻った時点で Wompi がまだトランザクションを確認していない場合、Wompi での支払いの確認を待っています。確認されるとメールが届きます。 というページが Check again ボタン付きで表示されます。Wompi のイベントが届くと、その時点で注文が作成されます。

支払いが拒否された場合は注文は作成されず、カートは保持されます。購入者はチェックアウトに戻り、Wompi での支払いは承認されませんでした（...）。もう一度試すか、別の支払い方法を選択できます。 と、Wompi が示した理由とともに表示されます。取り消された支払いには Wompi での支払いは取り消されました。もう一度試すか、別の支払い方法を選択できます。 と表示されます。購入者が支払わずに Web Checkout を離れた場合のメッセージは Wompi での支払いは完了しませんでした。もう一度試すか、別の支払い方法を選択できます。 です。新しい試行ごとに新しい参照番号が割り当てられます。カートに注文（支払い済み、保留中、支払いエラー、キャンセル）が生成された後は、再び支払うことはできません。購入者は注文確認ページに案内されます。

支払い方法は、ライセンスが有効で、現在のモードの 4 つのキーがすべて設定され、カートの通貨が COP でモジュールに許可されており、合計金額が COP 1,500 以上の場合にのみ表示されます。支払いを開始できない場合、購入者はチェックアウトに留まり、短いメッセージが表示されます：

イベント URL は、ストアがメンテナンスモードの間も動作し、ストアの国による制限でブロックされることはありません。

モジュールは PrestaShop からの返金を行いません。貴サイトには保存済みカード、サブスクリプション、カード入力欄はありません。すべての決済データは Wompi で入力されます。

注文

注文ステータス

まだ注文はありません: 購入者は Wompi に移動しましたが、まだ支払っていないか、支払いが拒否されたか、Wompi がまだトランザクションを確認していません。カートだけが存在します。

Awaiting Wompi payment: Wompi がトランザクションを保留中と報告しています。例えば、確認を待っている PSE、Nequi、現金払いです。Wompi が承認または拒否するまで注文は待機します。承認されると支払いが記録され、注文は Payment accepted に移ります。

Payment accepted: トランザクションがカート金額（COP）で承認されました。支払いは Wompi のトランザクション ID とともに記録され、メモにはトランザクション、支払い方法の種類（例：CARD、PSE、NEQUI）、参照番号、金額、環境が表示されます。

Wompi payment on hold: Wompi が注文合計と異なる金額または通貨を承認した場合（例：支払いが始まった後にカートが変更された場合）、または注文がキャンセルされた後に支払いが承認された場合です。注文は支払い済みとしてマークされません。メモに理由が説明されています。Wompi の管理画面で支払いを確認し、注文を処理するか、支払いを返金してください。

Payment error: 直近の支払い試行の保留中のトランザクションが拒否されたか、エラーで終了しました。Wompi のメッセージがメモに追加されます。古い試行の結果は注文を変更しません。

Canceled: 直近の支払い試行の保留中のトランザクションが Wompi で取り消されました。

既に支払い済みの注文に 2 件目の承認済み支払いが届いた場合、注文は変更されません。重複分を Wompi の管理画面で返金するようメモで求められます。支払いのトランザクションが Wompi で取り消された場合、注文を確認するようメモで求められます。返金済みの注文に対する遅れた支払いは、メモを追加するだけです。繰り返されるイベントや戻りによって、メモ、メール、支払いが重複することはありません。

Wompi 支払いブロック

注文ページには Wompi payment ブロックが表示され、参照番号、トランザクション ID、ステータス（Wompi のステータスを含む）、リクエストされた金額、トランザクションの金額、支払い方法、Wompi のメッセージ、サンドボックス支払い用の SANDBOX バッジ、カートに複数の支払い試行がある場合は Payment attempts、そして注文の Wompi notes が表示されます。

返金

返金は PrestaShop からは送信されません。Wompi の加盟店管理画面で支払いを返金または取り消してから、PrestaShop に返金を手動で記録してください。Wompi で行われた支払いトランザクションの取り消しは、メモとして注文に追加されます。

ライセンスキー

モジュールは vibefox.net から取得した VibeFox ライセンスキーで動作します。License — VibeFox Wompi Payment のライセンスブロックは、Modules > Module Manager > VibeFox Wompi Payment > Configure の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後ブロックには、キーがマスクされた状態、ステータス（例：ライセンスの有効期限日とドメイン）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-payment-wompi の行と、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 と日付。ショップのアドレスを変更した後、またはアカウントでドメイン枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。

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

有効なキーがないと、Wompi はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、あなたが管理画面にログインしていることを認識しないため、支払い方法はあなたにも非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブに通知が表示されます。既存の注文は影響を受けません。すでに開始されている支払いは、Wompi のイベントや購入者の戻りによって引き続き確認されます。

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

トラブルシューティング

Wompi がチェックアウトに表示されない: ライセンスが有効か、Enable/Disable がオンか、現在のモードの 4 つのキーがすべて設定されているかを確認してください（設定ページのステータスボックスに不足しているキーが表示されます）。カートの通貨が COP で、合計が COP 1,500 以上かも確認してください。Payment > Preferences で、モジュールが COP、購入者の国、購入者のグループに対して許可されているかを確認してください。

支払いは完了したのに注文が作成されない: イベント URL が機能していません。Wompi の管理画面で、使用中の環境（サンドボックスまたは本番）に対してイベント URL が設定されており、設定に表示されているものと完全に一致しているかを確認してください。その環境のイベントシークレットが該当するセクションにあるかも確認してください。注文は、購入者が支払い後にストアに戻ったときにも作成されます。

イベント URL が Not configured と応答する: イベントの環境のイベントシークレットが空です。設定に貼り付けてください。

イベント URL が Invalid signature と応答する: イベントシークレットが別の環境または別のアカウントのものです。Wompi の管理画面から再度コピーしてください。

イベント URL が Transaction lookup failed と応答する: Wompi API がトランザクションを返しませんでした。秘密キーの誤りやネットワークの問題などが原因として考えられます。Wompi は後でイベントを再送します。

イベント URL が Retry と応答する: 同じ瞬間に別のリクエストで注文が確認されていたか、注文を作成できませんでした（例：モジュールが無効になっている）。Wompi は後でイベントを再送します。理由は Log フィールドを確認してください。

イベント URL が Environment mismatch と応答する: サンドボックスのトランザクションが本番の支払い試行に対して届いた、またはその逆です。サンドボックスの支払いが本番の注文を確定することはありません。

イベント URL が Unknown reference と応答する: トランザクションの参照番号は、このストアが発行したものではありません。例えば、同じ Wompi アカウントが別のストアで使われている場合です。他のシステムの参照番号には Ignored と応答されます。

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

保存時に「キーが ... で始まっていません」という警告が出る: キーが誤ったセクションに貼り付けられています。サンドボックスのキーは pub_test_、prv_test_、test_events_、test_integrity_ で、本番のキーは pub_prod_、prv_prod_、prod_events_、prod_integrity_ で始まります。

注文が Wompi payment on hold になっている: Wompi payment ブロックのメモを読み（注文ステータスを参照）、その後、注文を処理するか、Wompi の管理画面で支払いを返金してください。

その他のエラー: モジュールページの Log フィールドと、注文の Wompi notes を確認してください。エラーは常に記録されます。詳細が必要な場合は Debug log をオンにしてください。

アンインストール

Modules > Module Manager に移動し、VibeFox Wompi Payment の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンス状態は常に削除されます。Delete data on uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。Wompi の支払い試行と、Awaiting Wompi payment および Wompi payment on hold の注文ステータスは常に保持されるため、古い支払いの遅れたイベントは再インストール後も認識されます。既存の注文は、支払いメモとトランザクション ID を保持します。

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