VibeFox ePayco for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。

PHP: 8.0 以降。

通貨: コロンビア・ペソ（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 つの zip ファイルで、両方の OpenCart バージョン用のパッケージが含まれています。コンピュータで解凍してください。README.txt、OpenCart 3 用のパッケージ wcp_epayco_payment-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ wcp_epayco_payment.ocmod.zip が含まれています。お使いの OpenCart バージョンのパッケージだけをインストールしてください。ライセンスキーは両バージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_epayco_payment-oc3-(version).ocmod.zip を選択します。この拡張機能には OCMOD の変更がないため、Extensions > Modifications を更新する必要はありません。インストーラーの代わりに、このパッケージの upload フォルダーの内容をストアのルートフォルダーにコピーすることもできます。

2. Extensions > Extensions に移動し、種類 Payments を選択します。VibeFox ePayco Payment を見つけて、Install（緑色の + ボタン）をクリックします。管理者ユーザーに、支払い拡張機能の一覧を変更する権限が必要です。

3. Edit（鉛筆ボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーを参照）。

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

5. Enable/Disable をオンにして Save をクリックします。Test Mode をオンにし、ePayco のテストカードで支払いをテストしてから、Test Mode をオフにします。

OpenCart 4

1. 管理画面で Extensions > Installer を開き、Upload をクリックして、ファイル wcp_epayco_payment.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から読み取るため、名前を変更したパッケージは動作しません。

2. インストール済み拡張機能の一覧に、同じページでパッケージが表示されます。その横の Install（緑色の + ボタン）をクリックしてください。

3. Extensions > Extensions に移動し、種類 Payments を選択します。VibeFox ePayco Payment を見つけ、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆ボタン）をクリックします。

4. ライセンスキー、ePayco のキー、および設定を、OpenCart 3 のステップ 3 から 5 と同じように入力してください。設定ページとそのフィールドは両バージョンで同じです。異なるのは確認 URL だけです（確認 URL を参照）。

新規インストールでは、支払い方法はオフ、テストモードもオフの状態で始まります。確認 URL は支払いのたびに ePayco に送信されるため、ePayco ダッシュボードで設定する必要はありません。

設定

すべての設定は拡張機能のページにあります: Extensions > Extensions > Payments > VibeFox ePayco Payment > Edit。セクションは左側に一覧表示されます。一覧の下にある Save ボタンで、ページ全体を保存します。設定の上部には、ePayco が取引を確認した後にのみ注文にステータスが付与されることが説明されています。4 つのキーのいずれかが未入力の場合（その場合、支払い方法はチェックアウトで非表示になります）や、ストアの既定の通貨が COP も USD でもない場合には警告が表示されます。テストモードが有効な間は、Test mode is on: customers pay with ePayco test cards and no real money is charged. と表示されます。拡張機能を変更する権限がない場合、ページは設定を表示しますが、保存はできません。

保存時、Title は 128 文字以内でなければならず、Sort Order は整数、Total は 0 以上の数値でなければならず、ジオゾーンと注文ステータスは存在している必要があります。そうでない場合はエラーが表示され、問題のある項目が示され、何も保存されません。

ePayco

Enable/Disable: Enable ePayco Payment で支払い方法のオン／オフを切り替えます。既定値: オフ。

Title: チェックアウトで購入者に表示される支払い方法の名称です。注文に保存される支払い方法名でもあります。128 文字まで。空の場合、購入者には ePayco と表示されます。既定値: ePayco。

Description: Confirm Order の手順で、確認ボタンの上に購入者へ表示されるテキストです。既定値: Pay securely with ePayco.

Sort Order: チェックアウトの支払い方法の中で ePayco が表示される順序です。空欄にするか、整数を入力します。

Geo Zone: 選択したジオゾーン内の支払い先住所に対してのみ ePayco を提供します。既定値: All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。

Total: ePayco が提供されるために注文が達している必要がある、ストアの既定通貨でのチェックアウト合計金額です。空欄にすると、どの金額でも 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 キーです。秘密にしてください。

保存済みの Secret Key (P_KEY) と Private Key (PRIVATE_KEY) は、再度表示されることはありません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。保存済みの値を削除するには、フィールドの下にある Clear saved secret on save にチェックを入れ、Save をクリックします。

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

チェックアウト

Checkout Type: ePayco のチェックアウトを開く方法です。

確認 URL

確認 URL は、支払いの結果をストアに伝えます。支払いのたびに自動的に ePayco に送信されるため、ePayco ダッシュボードで設定すべきことはありません。このセクションには URL が表示されます。その形式は、OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_epayco_payment/confirmation、OpenCart 4 では https://your-store/index.php?route=extension/wcp_epayco_payment/payment/wcp_epayco_payment.confirmation のようなもので、OpenCart のインストール先のストアフロントのアドレスから作成されます。インターネットからアクセスできる必要があり、ファイアウォールやベーシック認証でブロックされていてはいけません。OpenCart 3 では支払い拡張機能のリクエストが通過し、OpenCart 4 では拡張機能が確認 URL 用のスタートアップアクションを追加するため、ストアがメンテナンスモードでも動作します。

各確認には、お使いの P_CUST_ID_CLIENTE と P_KEY を使って作成された有効な署名が必要です。有効な署名のない確認は拒否され、何も変更されません。確認がない場合、注文は購入者が支払い後にストアに戻ったときにのみステータスを得ます。

注文

OpenCart は Confirm Order の手順で、ステータスのない注文（欠落した注文）を作成します。注文は ePayco が取引を確認した後にのみステータスを得ます。拒否されたり中断されたりした支払いでは、注文はステータスなしのままとなり、カートは保持されます。以下の各フィールドには、OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment: ePayco が支払いを承認し、金額と通貨が注文と一致した場合のステータスです。既定値: 処理中。

Awaiting Payment Status: ePayco が支払いを保留中または保留（PSE 振込、現金ネットワーク）として報告したときのステータスです。ePayco が承認または拒否すると、注文は自動的に変わります。既定値: 保留中。

On Hold (Review) Status: ePayco が、注文と金額または通貨の異なる支払いを承認した場合、または注文に別のステータス（例: キャンセル済み）が付与された後に承認した場合のステータスです。メモに理由が記載されます。ePayco ダッシュボードで取引を確認するまで発送しないでください。既定値: OpenCart に「保留」ステータスがないため、保留中。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

Payment Failed Status: 保留中の支払いが拒否された、失敗した、期限切れになった、またはキャンセルされた場合のステータスです。新たに承認された支払いは、引き続き注文を支払い済みにします。既定値: 失敗。

Reversed Status: ePayco が注文の支払いを取り消した場合のステータスです。既定値: 返金済み。

詳細設定

Logging: API のエラーと支払い確認を、OpenCart のログフォルダー（storage/logs）にある epc_p_debug.log.php に書き込みます。このファイルは Web から開くことができず、5 MB に達すると epc_p_debug.old.log.php に移動されます。キーや購入者のデータは記録されません。既定値: オフ。この設定がオフの間でも、エラーは常に記録されます。

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

Delete Data on Uninstall: オンにすると、拡張機能のアンインストール時に拡張機能の設定とログが削除されます。注文用に保存された ePayco のデータは、常に残ります。既定値: オフ。

インポート / エクスポート

Export: Download JSON で、設定を JSON ファイルとして保存します。秘密のキーはエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みの秘密のキーは保持されます。

チェックアウト

Payment Method の手順で、購入者は支払い方法を選択します（既定では ePayco）。Confirm Order の手順では、購入者にあなたの説明と、After confirming the order you pay securely in the ePayco checkout (cards, PSE, cash, wallets). という注記が表示されます。OpenCart はこの手順で注文を作成しますが、まだステータスはありません。OpenCart 4 では、支払い方法ブロックの Choose ボタンを押し、Payment method options ウィンドウで支払い方法を選んでから、チェックアウトページ下部の Confirm Order をクリックします。購入者が Confirm Order をクリックすると、拡張機能は注文通貨で注文合計金額の ePayco チェックアウトセッションを作成します。税金、注文番号、請求先の氏名、住所、メールアドレス、電話番号も含まれます。ePayco では、支払いは Order # と注文番号として表示されます。チェックアウトの言語は、購入者のストアの言語に応じてスペイン語または英語になります。

その後、購入者には 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 リンクもあります。Confirm Order を押すたびに、新しい ePayco セッションが作成されます（OpenCart 3 は Confirm Order のステップが表示されるたびに新しい注文を作成し、OpenCart 4 は注文を 1 つ保持して更新するため、新しい試行は同じ注文を支払います）。同じカートの以前の注文がすでに支払い済みか、ePayco の結果を待っている場合、購入者は注文成功ページに案内され、再度請求されることはありません。

ePayco のチェックアウトでは、購入者は ePayco アカウントで有効になっている支払い方法のいずれかで支払います。その後、ePayco は確認をストアに送信し、購入者を戻します。注文は、ePayco が確認した後にのみ支払い済みとしてマークされます。これは、署名付きの確認、または購入者が戻ったときにサーバー側から ePayco へ送るリクエストによって行われます。購入者が戻ってくるだけでは、注文は支払い済みになりません。その後、注文は通常の OpenCart の方法でステータスを得て、通常の注文メールと在庫の更新が行われ、購入者には OpenCart の注文成功ページが表示されます。

保留中の支払い（例: PSE または現金）の場合、注文は Awaiting Payment Status を得て、成功ページには 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. です。カートは保持され、注文はステータスなしのままです。OpenCart 4 では、これらのメッセージはチェックアウトページの上に表示されます。

OpenCart 4 は、成功ページが表示されるまで注文をチェックアウトに保持します。その間に、ePayco での支払いがないまま注文が閉じられた場合（たとえば保留中の支払いが失敗した、またはキャンセルした場合）、購入者は拒否された支払いについてのメッセージとともにチェックアウトに戻り、次の Confirm Order でそのカートの新しい注文の支払いが行われます。注文にすでにステータスがあり、その後カートが変更されている場合（数量の変更を含む）、購入者はチェックアウトに戻され、次の Confirm Order で新しいカートが新しい注文として支払われます。支払い済みの注文が、別のカートに対して支払い済みとして表示されることはありません。

ePayco が支払いを開始できない場合、購入者は Confirm Order の手順にとどまり、ボタンの上に短いメッセージが表示されます。例: We could not connect to ePayco. Please try again in a moment or choose another payment method. 技術的な理由はログに書き込まれます。

この拡張機能は一回限りの支払いのみに対応しています。ストアからの返金、保存済みカード、サブスクリプション、分割払いには対応しておらず、保留中の取引について ePayco に問い合わせることもしません。注文は ePayco の確認と購入者の戻りによって更新されます。

注文

注文ステータス

No status (missing order): 購入者が ePayco に送られた後、支払いをしていない、ePayco がまだ支払いを確認していない、または支払いが拒否された場合です。Sales > Orders では、このような注文は Order Status のフィルターを Missing Orders に設定した場合にのみ表示されます。

Order Status After Payment (default Processing): ePayco が支払いを承認しました。メモには ePayco の参照番号、状態、金額、支払い方法、承認コードが表示されます。

Awaiting Payment Status (default Pending): ePayco が支払いを保留中または保留として報告しました（例: PSE 振込や現金支払い）。ePayco が承認すると、注文は Order Status After Payment に移ります。拒否された、失敗した、期限切れになった、またはキャンセルされた場合は、注文は Payment Failed Status に移ります。OpenCart は、これらの変更について購入者にメールを送信します。

On Hold (Review) Status (default Pending): ePayco が、注文と金額または通貨の異なる支払いを承認したか、または注文に別のステータス（例: キャンセル済み）を設定した後に支払いを承認しました。メモにその内容が説明されます。発送前に ePayco ダッシュボードで取引を確認してください。

Payment Failed Status (default Failed): 保留中の支払いが完了しませんでした。メモには ePayco の理由が表示されます。新たに承認された支払いは、引き続き注文を支払い済みにします。遅れて発生した失敗が、支払い済みの注文を変更することはありません。

Reversed Status (default Refunded): ePayco が、この注文を支払った取引を取り消しました。

すでに支払い済みの注文について、ePayco が別の承認済み支払いを報告した場合、ステータスは変更されません。メモで、二重請求がないか確認し、必要に応じて ePayco で返金するよう求められます。購入者が同じカートの 2 つ目の注文を支払った場合（例: 開いている 2 つの ePayco ウィンドウから）、その注文にはステータスが付与されず、購入者には注文成功ページが表示され、支払い済みの注文には、2 つ目の支払いを ePayco で返金するよう求めるメモが付きます。本番モードで行われた注文に対するテスト取引や、すでに別の注文に紐づいている取引は無視されます。メモは、購入者には表示されない注文の History のエントリーです。

VibeFox ePayco Payment タブ

Sales > Orders で、ePayco で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox ePayco Payment タブには、ePayco reference (ref_payco)、Transaction ID、State、Payment method、Approval code、Transaction date、Mode（テスト支払いには Test mode ラベルが付く）、Attempt status、そして注文の ePayco notes が表示されます。レビュー中の注文の場合、タブには発送前に取引を確認するよう警告が表示されます。タブは読み取り専用で、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

ストアからの返金はサポートされていません。ePayco ダッシュボードで支払いを返金し、必要に応じて OpenCart で注文を手動で更新してください。ePayco が報告する支払い取引の取り消しは、注文を Reversed Status に設定します。Sales > Returns での商品返品では、ePayco を通じて返金は行われません。

ライセンスキー

この拡張機能は、vibefox.net で入手した VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox ePayco Payment は、Extensions > Extensions > Payments > VibeFox ePayco Payment > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例: ライセンスが有効な日付とドメイン）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-payment-epayco の行と、アカウントで vibefox.net を開く Manage licenses and domains in your account のリンクがあります。拡張機能に対する Modify 権限を持つ管理者ユーザーのみが、キーを変更できます。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれます）。

キーが受け付けられない場合、ブロックは理由を表示します。例: Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認された状態で動作を続けます。

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

有効なキーがない場合、チェックアウトで ePayco は購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。同じブラウザーで管理画面にログインしている管理者ユーザーには、ストアで支払い方法が (unlicensed — visible to admins only) と付いた状態で引き続き表示されるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面へのログインを認識しないため、有効なキーがない場合は、すべての人に対して決済方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間は非表示になります。既存の注文には影響しません。すでに開始された支払いは引き続き確認されます。

ライセンスが期限切れになった場合でも、拡張機能は動作を続けますが、更新とサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスは自動的に再確認されます。キーの入力後最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

ePayco does not appear at checkout: ライセンスが有効であること、Enable/Disable がオンであること、4 つのキーがすべて入力されていること、購入者が COP または USD で支払っていることを確認してください。キーが不足している場合、設定ページに警告が表示されます。支払い先住所が選択した Geo Zone にあること、注文が設定の Total に達していることも確認してください。

The payment went through, but the order stays without a status: ePayco の確認がストアに届いていません。設定に表示されている確認 URL がインターネットから開けること、ファイアウォール、セキュリティ拡張機能、ベーシック認証によってブロックされていないことを確認してください。拡張機能のページの Log フィールドを確認し、すべての確認を見るには Logging をオンにしてください。購入者が支払い後にストアに戻った場合も、注文はステータスを得ます。

Confirmation answers Invalid signature: Customer ID (P_CUST_ID_CLIENTE) または Secret Key (P_KEY) が、支払いを受け取った ePayco アカウントと一致しません。ePayco ダッシュボードから両方を再度コピーしてください。

Confirmation answers Gateway not configured: P_CUST_ID_CLIENTE または P_KEY が空です。設定で入力してください。

Confirmation answers Order not found: 確認は、このストアの ePayco 支払いがない注文を参照しています。

Confirmation answers Busy, retry later: 注文が同時に別のリクエストによって更新されていました。ePayco は確認を再試行します。理由はログに記録されています。

The customer sees We could not connect to ePayco: ePayco が PUBLIC_KEY と PRIVATE_KEY を拒否しました。ログには ePayco の応答が表示されます。両方のキーを再度コピーしてください。

The customer sees ePayco could not start the payment: ePayco がチェックアウトセッションを作成しませんでした。ログで ePayco のエラーを確認してください。

The customer sees This payment method is not available right now: チェックアウトセッションが注文と一致しなくなった、その間に支払い方法がオフにされた、またはキーが削除されました。購入者はチェックアウトを再読み込みします。

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

A test payment did not pay the order: テスト取引が、本番モードで行われた注文を支払うことはありません。Test Mode がオンの間に、テスト注文を行ってください。

Order is in the review status after payment: VibeFox ePayco Payment タブのメモを確認し（注文ステータスを参照）、発送前に ePayco ダッシュボードで取引を確認してください。

アンインストール

Extensions > Extensions に移動し、種類 Payments を選択して、VibeFox ePayco Payment の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します: Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータス。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、そのイベントに加え、メンテナンスモードでも ePayco の確認と戻りを通過させるスタートアップアクションも削除されます）。Delete Data on Uninstall がオンの場合、その他の支払い設定（タイトル、説明、キー、テストモード、チェックアウトの種類、ログ）とログが削除されます。オフの場合、後で再インストールするために保持されます。注文用に保存された ePayco のデータは常に保持されるため、古い注文の遅延した確認は再インストール後も引き続き機能します。既存の注文は支払いメモを保持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox ePayco Payment の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、Delete（赤いごみ箱のボタン）をクリックして、アップロードしたパッケージを削除します。

ePayco は、それぞれの所有者の商標です。本拡張機能は ePayco と提携しておらず、ePayco による推奨も受けていません。