VibeFox eWAY for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認済み）、または 4.0.2 以降（4.1.0.3 で動作確認済み）。

PHP: 8.0 以降（cURL 拡張機能付き）。

通貨: AUD、NZD、SGD、HKD、または MYR。それ以外のチェックアウト通貨では、チェックアウトで支払い方法が非表示になります。支払いは注文通貨で処理されます。

eWAY アカウント: Rapid API へのアクセス権を持つ eWAY 加盟店アカウントと、その Rapid API キーおよびパスワードが必要です。これらは MyeWAY の Settings, API Key から確認できます。テストには、独自のキーとパスワードを持つ eWAY サンドボックスアカウントが必要です。サンドボックスと本番のキーは異なります。MyeWAY での設定は不要です。戻り先 URL は支払いごとに送信されます。

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

インストール

ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで展開してください。含まれるのは README.txt、OpenCart 3 用パッケージ wcp_eway_payment_gateway-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_eway_payment_gateway.ocmod.zip です。お使いの OpenCart のバージョンに対応するパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

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

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

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

4. サンドボックスの API キーとパスワードを入力し、Sandbox Mode をオンのままにして、Enable/Disable をオンにし、Save をクリックして、テスト注文を行います。

5. 本番の API キーとパスワードを入力し、Sandbox Mode をオフにして、Save をクリックします。

6. 必要に応じて、設定ページに表示される cron URL を、サーバーの cron ジョブに追加します（設定を参照）。

OpenCart 4

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

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

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

4. OpenCart 3 の手順 3 から 6 と同じように、ライセンスキー、eWAY のキー、cron URL を入力します。設定ページとそのフィールドは両方のバージョンで同じです。違うのは cron URL だけです（Re-check of lost returns (cron) を参照）。

新規インストール直後は、支払い方法がオフ、サンドボックスモードがオンの状態です。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > Edit。セクションは左側に一覧表示されます。一覧の下にある Save ボタンで、ページ全体を保存します。設定の上には、モードを示すバッジが表示されます：SANDBOX — payments go to the eWAY sandbox, no real money is charged. または LIVE — real payments are taken with the live API key. 現在のモードの API キーまたはパスワードが未入力の場合（その場合、支払い方法はチェックアウトに表示されません）や、ストアの既定通貨が eWAY でサポートされていない場合には、ページに警告が表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時、Title は 1〜128 文字、Sort Order は整数、Total は 0 以上の数値である必要があります。また、選択したジオゾーンと注文ステータスが存在している必要があります。条件を満たさない場合は何も保存されず、ページに修正すべき内容が表示されます。

eWAY

Enable/Disable: Enable eWAY Payment Gateway は、支払い方法のオン/オフを切り替えます。既定値：オフ。

Title: チェックアウトで購入者に表示される支払い方法の名前です。注文に保存される支払い方法名にもなります。既定値：Credit Card (eWAY)。必須、128 文字まで。

Description: Confirm Order のステップで、確認ボタンの上に購入者へ表示されるテキストです。既定値：Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

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

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

Total: eWAY を提供するために注文が達している必要があるチェックアウト合計金額です（ストアの既定通貨建て）。空欄にすると、どの金額でも eWAY を提供します。

API 認証情報

Rapid API キーとパスワードは、MyeWAY の Settings, API Key にあります。eWAY では、本番用とサンドボックス用のキーについてのガイドを提供しており、このセクションからリンクされています。サンドボックスと本番のキーは異なります。サンドボックスモードではサンドボックスの認証情報だけを、本番モードでは本番の認証情報だけを使用します。

Sandbox Mode: 支払いはサンドボックスのキーとパスワードを使って eWAY のサンドボックスに送られ、実際の代金は請求されません。既定値：オン。本番のキーで実際の支払いを受けるにはオフにします。オンの間、購入者は Confirm Order のステップで Test mode: no real payment is taken. を目にします。

Live API Key: お使いの eWAY 本番アカウントの Rapid API キーです。

Live API Password: お使いの eWAY 本番アカウントの Rapid API パスワードです。

Sandbox API Key: お使いの eWAY サンドボックス（パートナー/開発者）アカウントの Rapid API キーです。

Sandbox API Password: お使いの eWAY サンドボックスアカウントの Rapid API パスワードです。

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

Return URL: 拡張機能の戻り先アドレスを表示します。注文と支払い試行のランダムなキーとともに、支払いごとに自動的に eWAY へ送信されるため、MyeWAY での設定は不要です。支払いの結果は、常に eWAY からサーバー間通信で読み取られます。

Re-check of lost returns (cron): Return URL の下に表示される、任意の cron URL です。サーバーの cron ジョブから 15 分ごとに（たとえば curl で）呼び出してください。購入者が支払い後、ストアに戻る前にブラウザーを閉じた場合、購入者が eWAY に送られてから約 60 分後に、eWAY へ支払いが問い合わせられ、注文が更新されます。eWAY に接続できない場合、確認は最大 3 回まで繰り返されます。この URL は秘密にしてください。インストール時に作成された秘密のトークンが含まれており、誤ったトークンで呼び出すと Forbidden が返されます。OpenCart 4 では、URL は https://your-store/index.php?route=extension/wcp_eway_payment_gateway/payment/wcp_eway_payment_gateway.cron&token=(token) の形式です。

注文

OpenCart は、Confirm Order のステップで、ステータスなし（注文欠落）の注文を作成します。注文がステータスを受け取るのは、eWAY が支払いを確認した後だけです。以下の各項目には、お使いの OpenCart の注文ステータスが表示されます。

Order Status on Success: eWAY が支払いを確認したときに設定されるステータスです。既定値：処理中。

eWAY payment on hold status: 承認されたものの、確認が必要な支払いのためのステータスです。金額または通貨が注文と一致しない場合、購入者が eWAY のページで Cancel をクリックした後に支払いが承認された場合、または注文がすでに別のステータスになっていた場合に使用されます。注文履歴のメモに理由が記録されます。既定値：保留中（OpenCart には On hold ステータスがないため）。独自のステータスを System > Localisation > Order Statuses で作成し、ここで選択できます。

Refunded order status: 注文ページから支払いを全額返金した後のステータスです。既定値：返金済み。

詳細設定

Debug log: API の呼び出しと支払い結果を、OpenCart のログフォルダー（storage/logs）にある eway_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。サイズが 5 MB に達すると、eway_p_debug.old.log.php に移動されます。カードデータ、キー、パスワード、購入者のメールアドレス、アクセスコードは記録されません。エラーは常に記録されます。既定値：オフ。

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

Delete all extension data on uninstall: オンにすると、拡張機能をアンインストールしたときに、ゲートウェイの設定とログが削除されます。注文の eWAY の支払いと返金の記録は常に保持されます。既定値：オフ。

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

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

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

チェックアウト

Payment Method のステップで、購入者は支払い方法を選択します（既定では Credit Card (eWAY)）。Confirm Order のステップでは、購入者にあなたの説明と、You will be redirected to the secure eWAY payment page to pay by card. という注記が表示されます。OpenCart はこのステップで注文を作成しますが、まだステータスは設定しません。OpenCart 4 では、購入者は支払い方法のブロックにある Choose ボタンを使い、Payment method options ウィンドウで支払い方法を選択して、チェックアウトページ下部の Confirm Order をクリックします。購入者が Confirm Order をクリックすると、拡張機能は eWAY に対し、注文通貨での注文合計額の支払いページを要求します。請求書参照として OC- と注文番号を指定し、購入者の支払い住所とメールアドレスも添えて、購入者を eWAY の安全な支払いページ（Responsive Shared Page）に移動させます。購入者はそのページでカードにより支払います。支払いは直ちに確定されます。

支払い後、購入者はストアに戻ります。拡張機能はブラウザーを信用しません。この注文のために作成された支払いページの結果を、eWAY にサーバー間通信で問い合わせます。注文は、eWAY が確認し、承認された金額と通貨が注文と一致した場合にのみ、支払い済みとしてマークされます。その後、注文は OpenCart の標準的な方法でステータスを受け取り、通常の注文メールと在庫の更新が行われ、購入者には OpenCart の注文完了ページが表示されます。承認保留中の注文の場合、ページにはさらに Your payment was received and is being reviewed by the store. We will contact you if anything is needed. が表示されます。

その時点で eWAY に問い合わせられない場合、Payment confirmation ページに We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again. が表示され、Check again ボタンと Back to checkout ボタンが表示されます。購入者が再確認したとき、または cron URL が実行されたときに、注文はステータスを受け取ります。

支払いが拒否された場合、購入者は理由とともにチェックアウトに戻されます。例：Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. 注文はステータスなしのままです。購入者が eWAY のページで Cancel をクリックした場合、拡張機能はまず eWAY に問い合わせて、何も支払われていないことを確認します（たとえば別のタブで支払われていないか）。その後、購入者には You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. が表示されます。支払いが完了しなかった場合のメッセージは The payment was not completed. Please try again. です。いずれの場合も、カートは保持されます。OpenCart 4 では、これらのメッセージがチェックアウトページの上に表示されます。

購入者は再試行できます。OpenCart 3 では、Confirm Order のステップが表示されるたびに新しい注文が作成されます。OpenCart 4 では注文が更新されるため、新しい試行では同じ注文に対して新しい eWAY の支払いページが開かれます。新しい支払いページを作成する前に、この注文と同じカートの他の注文の以前の支払いページが eWAY で確認されます。そのうちの 1 つがすでに支払い済みであれば、2 回目の支払いを行わず、その支払いが確認されます。それらについて eWAY に問い合わせできない場合、購入者には We could not check the status of your previous payment attempt. Please try again in a moment. が表示されます。eWAY が支払いページを作成できない場合、購入者は Confirm Order のステップにとどまり、短いメッセージが表示されます。例：Payment error: Unable to connect to eWAY. Please try again. または、eWAY のエラーコードとともに eWAY could not start the payment。

OpenCart 4 では、成功ページが表示されるまで注文がチェックアウト内で保持されます。その間に支払いなしで注文が閉じられた場合（たとえばキャンセルした場合）、購入者は Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. というメッセージとともにチェックアウトに戻されます。次の Confirm Order では、カートの新しい注文に対して支払いが行われます。その注文がすでに支払い済みでも、数量の変更を含め、その後にカートが変わっている場合は、Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. というメッセージが表示されます。支払い済みの注文が、別のカートについて支払い済みとして表示されることは決してありません。

戻り先 URL と cron URL は、OpenCart 3 が支払い拡張機能のリクエストを通過させ、OpenCart 4 では拡張機能がそのための起動アクションを追加するため、ストアがメンテナンスモードの間も機能します。

eWAY は Shared Page について、サーバー間通信による通知を送信しません。結果は、購入者が戻ったときと cron URL によって取得されます。この拡張機能は、お使いのサイト上にカード入力欄を持たず、保存済みカードやサブスクリプションもなく、オーソリのみやその後のキャプチャ（売上確定）もサポートしません。また、Beagle の不正スコアは評価しません（eWAY の不正防止ルールによってブロックされた取引は、eWAY 自身によって拒否されます）。

注文と返金

注文ステータス

No status (missing order): 購入者は eWAY に移動されたものの、支払っていない、キャンセルした、支払いが拒否された、または結果をまだ取得できていない状態です。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。

Order Status on Success (default Processing): 支払いが承認されました。メモには、eWAY のトランザクション ID、承認コード、レスポンス、モード（サンドボックスまたは本番）が表示されます。

eWAY payment on hold status (default Pending): eWAY が注文と異なる金額または通貨を承認した（例：Approved for partial amount）、購入者が eWAY のページでキャンセルした後に支払いが承認された、またはお客様がすでにステータスを設定していた注文に対して承認された（例：Canceled）場合です。eWAY が実際に引き落とした金額が記録され、メモでその内容が説明されます。注文を確認し、処理するか、支払いを返金してください。

Refunded order status (default Refunded): 支払いが拡張機能を通じて全額返金されました。

すでに支払い済みの注文、または同じカートの別の注文に対して 2 回目の支払いが承認された場合、支払い済みの注文は変更されません。メモで、重複した支払いを MyeWAY で返金するよう求められます。別の請求書参照に対して承認された支払いが、注文に適用されることはありません。

メモは、購入者には表示されない注文の History のエントリーです。

VibeFox eWAY Payment Gateway タブ

Sales > Orders で、eWAY で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox eWAY Payment Gateway タブには、Sandbox または Live のラベル付きの eWAY transaction ID、Auth code、eWAY の Response、Invoice reference、支払いの Status、Paid / refunded の金額、返金フォーム、返金履歴、注文の eWAY notes が表示されます。このタブは、拡張機能へのアクセス権があるユーザーに表示されます。

返金

タブで金額を入力します（まだ返金されていない金額が自動で入力されます）。必要に応じて Reason (optional) を入力し、Refund via eWAY をクリックします。Refund this amount through eWAY? This cannot be undone. という確認に同意してください。全額返金と一部返金に対応しています。拡張機能を変更する権限が必要です（System > Users > User Groups で設定します）。返金は、eWAY が請求した金額と通貨で行われます。そのため、一部の金額で承認された後は、注文合計ではなく、購入者が実際に支払った金額までを返金できます。返金は、支払いが行われた環境（サンドボックスまたは本番）で送信されるため、その環境の API キーとパスワードが設定されている必要があります。eWAY が返金を拒否した場合、タブには eWAY refund failed: と eWAY のコードが表示され、返金は記録されません。返金が成功すると、eWAY の返金トランザクション ID とともに、返金履歴とメモに追加されます。全額返金の場合、注文は購入者に通知されることなく、また商品が在庫に戻されることもなく、Refunded order status に設定されます。これは手動によるステータス変更と同じです。一部返金の場合、ステータスは変わりません。返金は、eWAY が支払いを承認した後に利用できます。

Sales > Returns での商品の返品では、eWAY を通じて返金は行われません。MyeWAY で行われた返金は、OpenCart には同期されません。必要に応じて、注文を手動で更新してください。

ライセンスキー

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

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

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

有効なキーがない場合、eWAY はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には 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 ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは必ず削除されます。

トラブルシューティング

eWAY does not appear at checkout: ライセンスが有効か、Enable/Disable がオンか、現在のモードの API キーとパスワードが設定されているか（サンドボックスモードではサンドボックスのフィールド、本番モードでは本番のフィールド）、そしてチェックアウト通貨が AUD、NZD、SGD、HKD、または MYR であるかを確認してください。認証情報が未入力の場合、設定ページに警告が表示されます。また、支払い住所が選択した Geo Zone に含まれているか、注文が設定の Total に達しているかも確認してください。

The payment went through, but the order stays without a status: 購入者が eWAY から戻らなかったか、その時点で eWAY に問い合わせできませんでした。eWAY は Shared Page について通知を送信しません。Re-check of lost returns (cron) の cron URL を設定してください。約 1 時間後に支払いが取得されます。MyeWAY でトランザクションを確認し、拡張機能のページにある Log フィールドを確認してください。

The cron URL answers Forbidden: URL 内のトークンが正しくありません。設定ページに表示された URL を、そのまま正確にコピーしてください。

The customer sees This payment method is temporarily unavailable: 現在のモードの API キーまたはパスワードがないか、eWAY がそれらを拒否しました。現在のモードの認証情報を確認してください。

The customer sees eWAY could not start the payment: eWAY がエラーコードを返しました。コードはメッセージに表示されます。多くの場合、請求情報が無効です。

The customer sees eWAY cannot take payments in a currency: 注文通貨が、eWAY で扱える通貨ではありません。AUD、NZD、SGD、HKD、または MYR を使用してください。

The customer sees We could not match this payment to an order: 戻りリンクがこのストアの注文に属していないか、eWAY が別の請求書参照の支払いを承認しました。購入者が請求された場合は、MyeWAY で支払いを確認してください。

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

Order is in the on hold status after payment: VibeFox eWAY Payment Gateway タブの eWAY notes を確認し（注文ステータスを参照）、注文を処理するか、支払いを返金してください。

No refund form in the tab: タブに理由が表示されます。注文の eWAY トランザクション ID が見つからない、全額返金済みである、ユーザーグループに拡張機能を変更する権限がない、または支払いのモードの API 認証情報が設定されていない、のいずれかです。

Refund fails with a message about the sandbox or live mode: 注文はその環境で支払われており、その環境の API キーとパスワードが設定されていません。入力してから再試行してください。

Refund fails with at most … can be refunded: 返金額が、eWAY が請求した金額から既存の返金額を引いた額を超えています。

開発者向け：拡張機能は、OpenCart のイベント wcp_eway_payment_gateway_supported_currencies（eWAY アカウントでより多くの通貨が有効になっている場合）と wcp_eway_payment_gateway_create_access_code_request（支払いページが作成される前のリクエスト本文）を発火させます。

アンインストール

Extensions > Extensions に進み、種類で Payments を選択して、VibeFox eWAY Payment Gateway の横にある Uninstall（赤色の − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します。具体的には、Enable/Disable、Sort Order、Geo Zone、Total、そして Orders セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、そのイベントと、メンテナンスモード中も戻り先 URL と cron URL を通過させる起動アクションも削除されます）。Delete all plugin data on uninstall がオンの場合、その他のゲートウェイ設定（タイトル、説明、サンドボックスモード、API キーとパスワード、デバッグログのスイッチ、cron トークン）とログが削除されます。オフの場合は、後で再インストールするために保持されます。eWAY の支払いと返金の記録は常に保持されるため、再インストール後も、以前に支払われた注文を返金できます。既存の注文は、支払いメモを保持します。

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

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