VibeFox ECPay for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

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

通貨: 新台湾ドル（TWD）。ECPay は TWD のみで決済するため、決済方法は購入者のカートが TWD の場合にのみ表示されます。ショップに TWD がない場合は、International > Localization > Currencies で追加してください。ECPay は小数を受け付けないため、金額は整数の TWD で送信されます。カートの合計は最も近い整数に四捨五入されます。端数が出ないように、TWD の価格には小数点以下 0 桁を使用してください。

ECPay アカウント: 実際の決済には、ECPay の加盟店アカウントの MerchantID、HashKey、HashIV が必要です。これらは ECPay の加盟店管理画面（vendor.ecpay.com.tw）で確認できます。テストには ECPay アカウントは不要です。

サイトへのアクセス: ECPay が決済通知を送信できるように、ショップはインターネットから HTTP/HTTPS でポート 80/443 を介してアクセスできる必要があります。サイトの前にあるファイアウォールやベーシック認証は、通知をブロックします。

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

インストール

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

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

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

4. Enable/Disable をオンにし、決済方法を選択し、最初のテストでは Test Mode をオンのままにします。Save をクリックします。

5. 実際の決済を行うには、Merchant ID、Hash Key、Hash IV（設定の項を参照）を入力し、Test Mode をオフにして、Save をクリックします。

インストール時に、モジュールは 2 つの注文ステータス Awaiting ECPay payment と ECPay payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを提供します。これらは Payment > Preferences で制限できます。ただし、モジュールに対して TWD は許可されたままにしておく必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、ショップに TWD 通貨がない場合はエラー（この場合、チェックアウトに ECPay は表示されません）、デフォルト通貨が TWD でない場合は警告（この場合、ECPay は TWD で支払う購入者にのみ表示されます）が表示されます。本番モードで MerchantID、HashKey、HashIV が未入力の場合はエラーが表示されます。テストモードがオンの間は、決済は公開テスト加盟店 3002607 の ECPay サンドボックスに送られ、お金は徴収されないこと、そして公開サンドボックスキーを知っている人なら誰でもテスト注文を確定できてしまうことについて警告が表示されます。そのため、実際の注文を受け付ける前にテストモードをオフにしてください。

ECPay（綠界）

Enable/Disable: Enable ECPay Payment は決済方法をオンまたはオフにします。デフォルト: オフ。

Title: チェックアウト時に購入者に表示される決済方法の名前です。注文に保存される決済方法の名前にもなります。デフォルト: ECPay（綠界）。必須: 空欄のままではページを保存できません。

Description: チェックアウト時に決済方法の下に表示されるテキストです。デフォルト: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode)。

ECPay アカウント

MerchantID、HashKey、HashIV は、ECPay の加盟店管理画面（vendor.ecpay.com.tw）の System development management > System integration settings（系統開發管理 > 系統介接設定）で確認できます。

Test Mode: 公開されている ECPay テスト加盟店 3002607 を使用して、決済を ECPay サンドボックス（payment-stage.ecpay.com.tw）に送信します。実際のお金は動きません。以下の認証情報は、テストモードがオフの場合にのみ使用されます。デフォルト: オン。オンの間、購入者には決済方法の下に TEST MODE — ECPay sandbox, no real money is charged. と表示されます。

Merchant ID: ECPay の Merchant ID（本番用）。テストモードでは無視されます。

Hash Key: ECPay の Hash Key（本番用）。テストモードでは無視されます。

Hash IV: ECPay の Hash IV（本番用）。テストモードでは無視されます。

貼り付けた認証情報に含まれるスペースや改行は、すべての署名を壊してしまうため、保存時に削除され、ページにその旨が表示されます。保存済みの Hash Key と Hash IV は再表示されません。フィールドは空のままになり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved secrets: Hash Key または Hash IV にチェックを入れて Save をクリックすると、削除されます。空のフィールドの場合は、保存済みの値が維持されます。

決済オプション

Enabled Payment Methods: 購入者に提供される決済方法です。複数ある場合、購入者はチェックアウト時に選択します。ATM、CVS、バーコードの注文は、購入者が支払うまで Awaiting ECPay payment のままです。少なくとも 1 つの方法を選択する必要があります。1 つも選択されていない場合は、Credit Card が有効になり、ページにその旨が表示されます。デフォルト: Credit Card。

Credit Card: ECPay のページでカードによる決済を行います。

ATM (Virtual Account): 購入者は仮想銀行口座を受け取り、振り込みを行います。

CVS (Convenience Store): 購入者はコンビニで支払うための決済コードを受け取ります。

Barcode: 購入者はコンビニのバーコードを受け取ります。

Default Payment Method: 事前に選択されている決済方法です。有効な決済方法のいずれかである必要があります。そうでない場合は、最初に有効になっている決済方法が使用されます。デフォルト: Credit Card。

Order Prefix: ECPay の取引番号（MerchantTradeNo）の接頭辞で、最大 5 文字の英字または数字です。保存時にその他の文字は削除され、メッセージが表示されます。複数のショップが 1 つの ECPay アカウントを共有する場合に便利です。各ショップに独自の接頭辞を付けてください。デフォルト: EC。

決済通知

ECPay は決済結果をショップに送信します。このセクションには Notification URL が表示されます。フレンドリー URL を使用している場合は、https://your-shop/module/wcp_ecpay_payment_gateway/notify のような形になり、場合によっては /en/ のような言語コードが付きます。この URL は決済のたびに送信されるため、ECPay 側で設定する必要はありません。ただし、インターネットからポート 80/443 でアクセスできる必要があり、その前にファイアウォールやベーシック認証があってはいけません。ショップのメンテナンスモードや国による制限によってブロックされることはありません。

各通知は、決済を開始した環境（テストまたは本番）のキーを使用して CheckMacValue 署名で検証され、その決済の MerchantID でも検証されます。有効な署名がない通知は拒否され、ECPay は再送します。通知がなければ注文は作成されません。ECPay の管理画面で決済を確認してください。

詳細設定

Enable Logging: 注文 ID、取引番号、金額、ECPay の戻りコードを、モジュールフォルダ内の logs/ecpay_p_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。キーや購入者データは記録されません。このスイッチがオフの場合でも、エラーは常に記録されます。デフォルト: オフ。

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

Delete Data on Uninstall: オンの場合、モジュールをアンインストールすると、その設定とログが削除されます。ECPay の決済記録と注文ステータスは常に保持されるため、既存の注文は再インストール後も機能し続けます。デフォルト: オフ。

チェックアウト

支払いの段階で、購入者は決済方法を選択します（デフォルトは ECPay（綠界））。複数の方法が有効な場合、購入者は Payment Method の下で Credit Card、ATM (Virtual Account)、CVS (Convenience Store)、Barcode のいずれかも選択します。

確認後、購入者には Redirecting to ECPay for payment. Please wait... と表示され、ECPay の決済ページに移動します。リダイレクトが開始されない場合に備えて、Proceed to ECPay ボタンも表示されます。カートの合計は、商品名と数量とともに整数の TWD で送信されます。ECPay のページは、台湾語および香港の言語では繁体字中国語、これらの言語に対応する簡体字中国語、韓国語、日本語で表示され、それ以外のすべての言語では英語で表示されます。これは購入者のショップの言語に従います。この時点では、まだ注文は存在しません。

注文は、ECPay が署名付きのサーバー通知によって確認した後にのみ作成されます。購入者が ECPay のページでショップに戻るリンクをクリックし、注文がすでに存在する場合は、標準の注文確認ページが開きます。支払済みの注文の場合は Your ECPay payment has been received.、確認中の注文の場合は Your ECPay payment was received and is being reviewed by the store. が表示されます。支払い待ちの ATM、CVS、またはバーコードの注文の場合は、支払い案内が表示されます。通知がまだ届いていない場合は、Payment confirmation ページに We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment. と表示され、Check again と Back to checkout のボタンが表示されます。ECPay が決済の失敗を報告した場合、購入者は The payment was not completed. You can try again or choose another payment method. とともにチェックアウトに戻されます。カートは保持されます。

ATM、CVS、バーコードの場合、購入者にはまず支払いの詳細が提供されます。注文は Awaiting ECPay payment で作成され、銀行コードと仮想口座、コンビニの支払いコードまたはバーコード、金額、Pay before の日付が、注文確認ページおよび購入者の注文詳細の ECPay payment instructions に表示されます。購入者が支払うと、ECPay が別の通知を送信し、注文は支払済みとしてマークされます。支払い案内は PrestaShop のメールには追加されません。

ECPay は再利用された番号を拒否するため、試行ごとに新しい ECPay 取引番号が作成されます。そのため、決済に失敗した後の再試行は機能し、購入者がブラウザでリダイレクトページに戻った場合は新しい試行が開始されます。1 つのカートで最大 30 回まで決済を試行できます。カートに注文が作成されると、チェックアウトから再度支払うことはできません。支払い待ちの ATM または CVS の注文は、すでに発行された支払い情報を使用して支払います。

決済を開始できない場合、購入者は短いメッセージとともにチェックアウトに留まります。例えば、四捨五入後の合計が 1 TWD 未満の場合は、The order total is too small for ECPay. と表示されます。方法ごとの ECPay の金額上限は、チェックアウトではなく ECPay のページで確認されます。

このモジュールは、ECPay のページでのみ一回限りの決済を受け付けます。PrestaShop からの返金、保存済みカード、定期購入や定期定額（定期定額）、分割払い、Apple Pay、TWQR、WeChat Pay、BNPL、WebATM、電子インボイス、物流には対応しておらず、サーバー側でのステータス照会も行いません。ショップが通知を受信できない場合は、ECPay の管理画面で決済を確認してください。

注文

注文ステータス

No order yet: 購入者は ECPay に送られ、まだ支払っていないか、通知がまだ届いていません。存在するのはカートだけです。

Awaiting ECPay payment: 購入者は ATM、CVS、またはバーコードを選択し、支払いの詳細を受け取りました。メモには、銀行コードと仮想口座、支払いコードまたはバーコード、期限が表示されます。

Payment accepted: 決済が確定しました。決済は ECPay の TradeNo を取引 ID として記録され、メモには TradeNo、決済の種類、金額、取引番号が表示されます（サンドボックス決済には、テストモードのマークが付きます）。

ECPay payment on hold: ECPay がカートと異なる金額または通貨を報告した場合（例えば、決済の開始後に別のタブでカートが変更された場合）、本番モードに切り替えた後にサンドボックス決済が届いた場合（実際のお金は徴収されていません）、または注文がキャンセルされた後に決済が届いた場合（その場合、決済は記録されます）に、この状態になります。メモにその理由が説明されています。ECPay の管理画面と照合し、そのうえで注文を処理するか、決済の返金を行ってください。

Payment error: ECPay が、支払い待ちの注文の最新の ATM、CVS、またはバーコードの決済が失敗したと報告しました。メモには、ECPay の戻りコードとメッセージが表示されます。

重複した通知は無視されます。支払済み、返金済み、またはキャンセル済みの注文が、遅れて届いた失敗によって再度開かれることはありません。すでに支払済みの注文に対する 2 回目の決済（例えば 2 つのブラウザタブからの決済）は、1 回だけメモとして記録されるため、ECPay の管理画面で返金できます。ECPay の管理画面から開始されたシミュレーション決済は、メモとして記録されるだけで、注文を支払済みにすることはありません。ECPay はそれらに対してお金を徴収しないためです。

ECPay 決済ブロック

注文ページには、注文のすべての決済試行を示す ECPay payment ブロックが表示されます。サンドボックスの試行には Test mode バッジが付いた MerchantTradeNo、決済方法、TWD での金額、ステータス、ECPay の TradeNo、決済の種類と日付、そして ECPay の戻りコードが表示されます。その下には、注文の ECPay notes があります。ECPay payment on hold の注文の場合、このブロックは ECPay の管理画面と照合するよう注意を促します。

返金

PrestaShop からの返金は利用できません。ECPay の管理画面で決済を返金してから、PrestaShop で注文を手動で更新してください。注文ページにある PrestaShop の標準の返金ボタンでは、ECPay を通じて返金は行われません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに ECPay が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、購入者のカートが TWD であること、そして本番モードでは Merchant ID、Hash Key、Hash IV が設定されていることを確認してください。設定ページには、これらの各場合にメッセージが表示されます。Payment > Preferences で、モジュールが TWD、購入者の国、および購入者のグループに対して許可されていることを確認してください。

決済は完了したが、注文が作成されなかった: ECPay の通知がショップに届きませんでした（サイトのダウン、ファイアウォール、ベーシック認証）。ECPay は数回再試行します。ECPay の管理画面で取引を確認することもできます。モジュールが受信した通知を確認するには、Enable Logging をオンにしてください。拒否された通知は、いずれにしてもエラーとして記録されます。

通知が 0|CheckMacValue verification failed と応答する: Hash Key または Hash IV が ECPay アカウントと一致していないか、決済が別の環境で開始されています。ECPay の管理画面から再度コピーしてください。

通知が 0|MerchantID mismatch と応答する: 通知は、決済を開始したものとは別の ECPay 加盟店に属しています。

通知が 0|Order not found と応答する: 取引番号は、このショップが発行したものではありません。例えば、複数のショップが 1 つの ECPay アカウントを共有している場合です。各ショップに独自の Order Prefix を設定してください。

通知が 0|Retry と応答する: 同じ時刻に別の通知によってカートが処理されていたか、注文を作成できませんでした（例えば、モジュールが無効になっている場合）。ECPay は通知を再送します。理由を確認するには、Enable Logging をオンにしてください。

通知 URL に 0|Method not allowed in the browser と表示される: これは正常です。この URL は ECPay からのリクエストのみを受け付けます。

購入者に「The order total is too small for ECPay.」と表示される: カートの合計が四捨五入後に 1 TWD 未満であり、ECPay で支払うことができません。

購入者に「Too many payment attempts for this order」と表示される: カートが 30 回の決済試行に達しました。購入者に新しいカートを始めてもらってください。

注文が ECPay payment on hold になっている: ECPay payment ブロックのメモを確認し（注文ステータスの項を参照）、ECPay の管理画面と照合したうえで、注文を処理するか、決済の返金を行ってください。

開発者向け: フック actionEcpayPRequestParams を使うと、別のモジュールが ECPay に送信されるパラメータを変更できます。ただし、加盟店、取引番号、金額はこのフックでは変更できません。

アンインストール

Modules > Module Manager に移動し、VibeFox ECPay Payment Gateway の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete Data on Uninstall がオンの場合、設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。ECPay の決済記録と、Awaiting ECPay payment および ECPay payment on hold の注文ステータスは常に保持されるため、古い決済に対する遅れた通知は、再インストール後も引き続き確認されます。既存の注文は、決済のメモと取引 ID を保持します。

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