VibeFox ePayco for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

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

通貨：コロンビアペソ（COP）または米ドル（USD）。ほかの通貨のカートでは、チェックアウト時にこの決済方法は表示されません。

ePayco アカウント：ePayco アカウントの 4 つのキーが必要です：P_CUST_ID_CLIENTE、P_KEY、PUBLIC_KEY、PRIVATE_KEY。これらは ePayco の管理画面で Integrations, API keys の下にあります。テストモードと本番モードで同じキーを使用できます。購入者が利用できる決済方法（カード、PSE、現金払いのネットワーク、ウォレット）は、ePayco アカウントで有効になっているものです。

公開サイト：ショップの確認 URL はインターネットから到達可能で、ファイアウォールや基本認証によってブロックされていないことが必要です。

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

インストール

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

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

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

4. ePayco の 4 つのキーを入力し、チェックアウトの種類を選択します（設定を参照）。

5. Enable/Disable を有効にして Save をクリックします。Test Mode を有効にし、ePayco のテストカードを使って支払いをテストしてから、Test Mode を無効にします。

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox ePayco Payment > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。フィールドの上部では、4 つのキーがすべて入力されていない場合（その場合、チェックアウトで決済方法が非表示になります）や、ショップの既定の通貨が COP または USD でない場合に警告が表示されます。テストモードが有効な間は Test mode is on: customers pay with ePayco test cards and no real money is charged. と表示されます。

ePayco

Enable/Disable：Enable ePayco Payment で決済方法を有効または無効にします。既定値：無効。

Title：購入者がチェックアウトで見る決済方法の名前です。注文にも決済方法名としてこの名前が保存されます。既定値：ePayco。

Description：チェックアウトで決済方法の下に表示されるテキストです。既定値：Pay securely with ePayco.

ePayco アカウントのキー

4 つのキーは ePayco の管理画面で、Integrations, API keys の下にあります。P_CUST_ID_CLIENTE と P_KEY は支払いの確認通知を検証し、PUBLIC_KEY と PRIVATE_KEY はチェックアウトセッションを作成します。同じキーがテストモードと本番モードの両方で使えます。

Customer ID (P_CUST_ID_CLIENTE)：ePayco の顧客 ID（数字）。

Secret Key (P_KEY)：ePayco の支払い確認通知の署名を検証するために使用します。秘密にしてください。

Public Key (PUBLIC_KEY)：ePayco の公開 API キー。

Private Key (PRIVATE_KEY)：ePayco の秘密 API キー。秘密にしてください。

保存された秘密キーは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。

保存済みの秘密キーを消去：Secret Key (P_KEY) または Private Key (PRIVATE_KEY) にチェックを入れ、Save をクリックして削除します。フィールドを空のままにすると、保存されている値は維持されます。

Test Mode：チェックアウトセッションはテスト取引として作成されます。購入者は ePayco のテストカードで支払い、実際の金額は請求されません。テスト取引が本番モードで作成された注文を支払うことはありません。既定値：無効。有効な間、購入者は決済方法の下と支払いページに TEST MODE — use ePayco test cards, no real money is charged. と表示されます。

チェックアウト

Checkout Type：ePayco のチェックアウトの開き方です。

Popup (One Page)：ePayco のチェックアウトがショップのページの上に開きます（既定）。

Redirect：購入者は ePayco の決済ページに移動します。

確認 URL

確認 URL は、支払いの結果をショップに伝えます。支払いごとに自動的に ePayco へ送信されるため、ePayco の管理画面で設定する必要はありません。このセクションには URL が表示されます。フレンドリー URL が有効な場合は https://your-shop/module/wcp_epayco_payment/confirmation のような形になり、/en/ のような言語コードが付くこともあります。インターネットから到達可能で、ファイアウォールや基本認証によってブロックされていないことが必要です。ショップがメンテナンスモードの間も機能し、ショップの国による制限でもブロックされません。

各確認通知には、P_CUST_ID_CLIENTE と P_KEY を使って作成された有効な署名が含まれている必要があります。有効な署名のない確認通知は拒否され、何も変更しません。確認通知がない場合、注文は購入者が支払い後にショップへ戻ったときにのみ作成されます。

詳細設定

Logging：API のエラーと支払いの確認通知を、モジュールフォルダ内の logs/epc_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。キーや購入者データは記録されません。既定値：無効。無効のときでもエラーは常に記録されます。

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

Delete Data on Uninstall：有効にすると、モジュールをアンインストールしたときにモジュールの設定とログが削除されます。注文に保存された ePayco のデータとモジュールの注文ステータスは常に残るため、既存の注文は引き続き機能します。既定値：無効。

チェックアウト

支払いの段階で、購入者は決済方法（既定では ePayco）を選んで確定します。モジュールは、カートの合計額について、カートの通貨で ePayco のチェックアウトセッションを作成します。税金、カート番号、請求先の氏名、住所、メールアドレス、電話番号も含まれます。ePayco の画面では、支払いは Cart # とカート番号として表示されます。チェックアウトの言語は、ショップの言語に応じてスペイン語または英語です。この時点ではまだ注文は存在しません。

購入者は続いて ePayco payment ページを表示され、Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. と表示されます。ePayco のチェックアウトは、Checkout Type の設定に応じてポップアップまたはリダイレクトとして開きます。このページには Pay with ePayco ボタンと Choose another payment method のリンクもあります。支払いボタンをクリックするたびに、新しい ePayco セッションが作成されます。

ePayco のチェックアウトで、購入者は ePayco アカウントで有効になっている決済方法のいずれかを使って支払います。その後、ePayco は確認通知をショップに送信し、購入者を戻します。注文が支払い済みになるのは、ePayco が確認した後のみです。署名付きの確認通知によるか、購入者が戻ったときにサーバーから ePayco へ問い合わせることによります。購入者が戻っただけでは、注文は支払い済みになりません。その後注文が作成され、購入者には標準の注文確認ページが表示されます。

保留中の支払い（例：PSE や現金払い）の場合、注文は Awaiting ePayco payment で作成され、確認ページには Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. と表示されます。保留中の支払いが後で拒否されたり期限切れになったりした場合、ページには Your ePayco payment was not completed. Please contact us about this order. と表示されます。購入者が戻った時点でまだ ePayco が支払いを確認していない場合は、Payment confirmation ページに We are waiting for ePayco to confirm your payment. This page does not need to stay open. と表示され、Check again ボタンが表示されます。

支払いが拒否された場合、購入者は Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. と表示されたチェックアウトに戻ります。購入者が支払わずに戻った場合は、The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again. と表示されます。カートは保持され、注文は作成されません。

ePayco が支払いを開始できない場合、購入者はチェックアウトに残り、たとえば We could not connect to ePayco. Please try again in a moment or choose another payment method. という短いメッセージが表示されます。技術的な理由はログに記録されます。

モジュールは 1 回限りの支払いのみに対応しています。ショップからの返金、保存済みカード、サブスクリプション、分割払いには対応しておらず、保留中の取引について ePayco に定期的な問い合わせは行いません。注文は ePayco の確認通知と購入者の戻りによって更新されます。

注文

注文ステータス

No order yet：購入者は ePayco へ送られたものの、まだ支払っていない、ePayco がまだ支払いを確認していない、または支払いが拒否された状態です。カートのみが存在します。

Payment accepted：ePayco が支払いを承認しました。支払いは ePayco の参照番号（ref_payco）をトランザクション ID として記録され、メモには参照番号、状態、金額、決済方法、承認コードが表示されます。

Awaiting ePayco payment：ePayco が支払いを保留中または保留された状態として報告しています。例：PSE 振込や現金払い。ePayco が支払いを承認または拒否すると、注文は自動的に変わります。

ePayco payment on hold：ePayco が、注文と金額または通貨が異なる支払いを承認しました（例：支払いの開始後にカートが変更された）。または、注文がキャンセルされた後に支払いを承認しました。通貨が一致する場合、実際に支払われた金額が注文に記録されます。発送する前に、ePayco の管理画面でその取引を確認してください。

Payment error：保留中の支払いが拒否、失敗、期限切れ、またはキャンセルされました。メモには ePayco が示した理由が表示されます。カートに対する新しい承認済みの支払いは、引き続き注文を支払い済みにします。遅れて発生した失敗が支払い済みの注文を変更することはありません。

Refunded：ePayco がこの注文の支払いを取り消しました。

すでに支払い済みの注文について ePayco が別の承認済みの支払いを報告した場合、ステータスは変わりません。メモで二重請求がないか確認し、必要に応じて ePayco で返金するよう求められます。本番モードで作成された注文に対するテスト取引や、すでに別の注文に紐づいている取引は、メモ付きで無視されます。

ePayco 支払いブロック

注文ページには ePayco payment ブロックが表示され、ePayco 参照番号（ref_payco）、トランザクション ID、状態、決済方法、承認コード、取引日、テスト支払い用の Test mode バッジ、注文の ePayco notes が含まれます。ePayco payment on hold の注文では、発送前に取引を確認するよう警告が表示されます。

返金

ショップからの返金には対応していません。ePayco の管理画面で支払いを返金し、必要に応じて PrestaShop で注文を手動で更新してください。ePayco が報告した支払い取引の取消しは、注文を Refunded に設定します。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに ePayco が表示されない：ライセンスが有効か、Enable/Disable が有効か、4 つのキーがすべて入力されているか、カートの通貨が COP または USD かを確認してください。キーが不足していると、設定ページに警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループに対して許可されているかを確認してください。

支払いは完了したが注文が作成されなかった：ePayco の確認通知がショップに届いていません。設定に表示されている確認 URL がインターネットから開けること、ファイアウォール、セキュリティモジュール、基本認証によってブロックされていないことを確認してください。モジュールページの Log 欄を確認してください。すべての確認通知を見るには Logging を有効にします。購入者が支払い後にショップへ戻ったときにも注文は作成されます。

確認通知の応答が「Invalid signature」：Customer ID (P_CUST_ID_CLIENTE) または Secret Key (P_KEY) が、支払いを受け取った ePayco アカウントと一致していません。両方を ePayco の管理画面から再度コピーしてください。

確認通知の応答が「Gateway not configured」：P_CUST_ID_CLIENTE または P_KEY が空です。設定に入力してください。

確認通知の応答が「Order not found」：確認通知が、このショップの ePayco 支払いのないカートを参照しています。

確認通知の応答が「Busy, retry later」：注文が同時に別のリクエストによって更新されていたか、注文を作成できませんでした（例：モジュールが無効）。ePayco は確認通知を再試行します。理由はログにあります。

購入者に「We could not connect to ePayco」と表示される：ePayco が PUBLIC_KEY と PRIVATE_KEY を拒否しました。ログに ePayco の応答が表示されます。両方のキーを再度コピーしてください。

購入者に「ePayco could not start the payment」と表示される：ePayco がチェックアウトセッションを作成しませんでした。ログで ePayco のエラーを確認してください。

ePayco のチェックアウトが開かない：購入者に The ePayco checkout could not be loaded. Please reload the page or choose another payment method. と表示されます。支払いページで ePayco のチェックアウトスクリプトを読み込めませんでした。購入者はページを再読み込みするか、Choose another payment method を使用できます。

テスト支払いで注文が支払われなかった：テスト取引が本番モードで作成された注文を支払うことはありません。Test Mode を有効にした状態でテスト注文を行ってください。

注文が ePayco payment on hold になっている：ePayco payment ブロックのメモを確認し（注文ステータスを参照）、発送前に ePayco の管理画面で取引を確認してください。

アンインストール

Modules > Module Manager に移動し、VibeFox ePayco Payment の横のメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete Data on Uninstall が有効であれば、モジュールの設定とログが削除されます。無効であれば、後で再インストールできるようすべての設定が保持されます。注文に保存された ePayco のデータと、注文ステータス Awaiting ePayco payment および ePayco payment on hold は常に保持されます。既存の注文は、支払いのメモとトランザクション ID を保持します。

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