VibeFox SimplePay for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

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

ショップの通貨: HUF、EUR、USD のいずれか。SimplePay は他の通貨を受け付けず、それらの通貨のカートでは決済方法が表示されません。

SimplePay の加盟店アカウント: SimplePay では、通貨ごとに個別の加盟店アカウントが発行され、本番とサンドボックスでもアカウントは別々になります。各アカウントについて、SimplePay の加盟店管理画面（本番は admin.simplepay.hu、サンドボックスは sandbox.simplepay.hu）の account > Technical data から MERCHANT と SECRET KEY を取得してください。HUF でのみ販売する場合は、HUF アカウントだけで十分です。その他のキーは必要ありません。

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

インストール

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

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

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

4. 販売する通貨ごとに、SimplePay アカウントの MERCHANT と SECRET KEY を入力します。テストにはサンドボックスのアカウントを、実際の決済には本番のアカウントを使用してください（「設定」を参照）。

5. Configure ページに表示される IPN URL を、SimplePay の加盟店管理画面にある各加盟店アカウント（本番とサンドボックスの両方）にコピーします。

6. Enable/Disable を有効にして Save をクリックします。Sandbox mode を有効にした状態でテスト決済を行い、その後 Sandbox mode を無効にして実際の決済を受け付けます。

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox SimplePay Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。入力欄の上には、ショップの既定通貨が SimplePay に対応していない場合、または現在のモードでその通貨の加盟店アカウントがない場合に、警告が表示されます。どちらの場合も、その通貨のカートでは決済方法が表示されません。サンドボックスモードがオンのときは、ページに Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged. と表示されます。

SimplePay (OTP)

Enable/Disable: Enable SimplePay Gateway は決済方法をオンまたはオフにします。既定値：オフ。

Title: チェックアウトで購入者に表示される決済方法の名前です。注文に保存される決済方法の名前にもなります。既定値：SimplePay (Card Payment)。必須。

Description: チェックアウトで決済方法の下に表示されるテキストです。既定値：Pay securely with your credit or debit card via SimplePay。ハンガリーの加盟店は、ここに SimplePay のデータ転送に関する宣言（リンク付き）を記載できます。

Sandbox mode: サンドボックスのアカウントを使い、SimplePay のサンドボックスでテスト決済を行います。API のアドレスと加盟店アカウントの両方が切り替わります。実際の金額は請求されません。既定値：オン。本番のアカウントで実際の決済を受け付けるには、オフにします。オンの間、購入者には決済方法の下に Sandbox mode: no real payment is taken. と表示されます。サンドボックスで開始された注文は、常にサンドボックスで返金されます。

本番用の加盟店アカウント

Sandbox mode がオフのときに使用されるアカウントです。ショップで販売する通貨のアカウントを入力してください。MERCHANT と SECRET KEY の値は、SimplePay の加盟店管理画面（admin.simplepay.hu）の account > Technical data にあります。両方の欄が入力されている場合にのみ、そのアカウントが使用されます。

HUF account — Merchant ID: 本番の HUF アカウントの MERCHANT です。

HUF account — Secret key: 本番の HUF アカウントの SECRET KEY です。

EUR account — Merchant ID と EUR account — Secret key: 本番の EUR アカウントについても同様です。

USD account — Merchant ID と USD account — Secret key: 本番の USD アカウントについても同様です。

サンドボックス用の加盟店アカウント

Sandbox mode がオンのときに使用されるアカウントです。欄は本番のアカウントと同じです：HUF account — Merchant ID、HUF account — Secret key、および EUR と USD についても同じ組み合わせです。値は SimplePay のサンドボックス加盟店管理画面（sandbox.simplepay.hu）の account > Technical data から取得してください。

保存済みのシークレットキーは再表示されません。欄は空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

IPN URL

IPN は、決済ステータスが変わったときに SimplePay からショップへ送られるメッセージです。注文が作成される通常の方法です。このセクションには、ショップの IPN URL が表示されます。フレンドリー URL を使用している場合、https://your-shop/module/wcp_simplepay_gateway/ipn のような形になり、/en/ のような言語コードが付くこともあります。この URL は、SimplePay の加盟店管理画面で、各加盟店アカウント（本番とサンドボックスの両方）に設定してください。リダイレクトされた IPN は失われるため、URL は設定画面に表示されたとおりに正確にコピーしてください。

IPN は、指定された加盟店アカウントの SECRET KEY で、決済が開始されたモード（サンドボックスまたは本番）に合わせて署名されている必要があります。有効な署名のない IPN は拒否されます。モジュールは、有効な IPN のそれぞれを、SimplePay が要求する署名付きの形式で SimplePay に確認応答します。使用される IPN ステータスは次のとおりです。

FINISHED: 決済が成功しました。金額と通貨の確認の後に注文が作成されます。

NOTAUTHORIZED, FRAUD: 決済が拒否されました。決済の試行は失敗としてマークされ、注文は作成されません。

TIMEOUT, CANCELLED: 決済の制限時間が切れたか、購入者がキャンセルしました。決済の試行はタイムアウトまたはキャンセルとしてマークされ、注文は作成されません。

拒否、キャンセル、タイムアウトのステータスは、まだ注文がないカートの最新の決済の試行に対してのみ記録されます。その他のステータスはログに記録されますが、何も変更されません。IPN がない場合、注文は、購入者が決済成功後にショップへ戻ったときにのみ作成されます。

Clear saved secret keys: シークレットキーにチェックを入れて Save をクリックすると、削除されます。空欄の場合は、保存されている値が維持されます。

注文

Order Status After Payment: 決済が成功した後に設定される注文ステータスです。

Processing (Payment accepted): 既定値で、支払い済み注文に対する PrestaShop の標準ステータスです。

Completed (Delivered): 支払い済みのすべての注文が配達済みになります。

注文と金額または通貨が異なる決済は、常に SimplePay payment on hold になります。

詳細設定

Logging: API の呼び出し、IPN、戻りを、モジュールのフォルダ内にある logs/simplepay_op_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。キーや購入者データは記録されません。この設定がオフでも、エラーは常に記録されます。既定値：オフ。

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

Delete Data on Uninstall: オンにすると、モジュールをアンインストールしたときにゲートウェイの設定とログが削除されます。注文データ（SimplePay の取引と返金）は常に保持されます。既定値：オフ。

チェックアウト

支払いの段階で、購入者は決済方法（既定では SimplePay (Card Payment)）を選択し、You will be redirected to the SimplePay payment page to pay by card. という注記を確認します。確定すると、モジュールはカートの通貨で、カート合計金額に対する SimplePay のカード決済を、現在のモードでその通貨の加盟店アカウントを使って開始し、購入者を SimplePay の決済ページへ送ります。購入者のメールアドレスと、入力が完了している場合は請求先住所が SimplePay に渡されます。決済ページは、SimplePay が対応している場合はショップの言語、対応していない場合は英語で表示されます。開始された決済は 30 分以内に完了できます。この時点ではまだ注文は存在しません。

決済が成功すると、購入者はショップに戻ります。戻っただけでは注文は支払い済みになりません。モジュールは署名付きのリクエストで SimplePay に取引のステータスを照会するため、IPN が遅れて届いた場合でも注文は作成されます。注文は、SimplePay が確認した後にのみ支払い済みとしてマークされます。その後、購入者には標準の注文確認ページが表示され、Successful transaction. SimplePay transaction ID: と ID が示されます。SimplePay がまだ決済を確認していない場合は、Payment confirmation ページに Your payment is being confirmed by SimplePay. SimplePay transaction ID: と ID、そして Check again ボタンが表示されます。IPN が届き次第、注文が作成されます。

決済が失敗した場合、キャンセルされた場合、またはタイムアウトした場合、購入者は SimplePay のメッセージと取引 ID を伴ってチェックアウトに戻ります。例：Cancelled payment. You cancelled the payment または Timeout. The time allowed to complete the payment has expired。決済が失敗した場合は、入力したデータを確認し、カードを発行した銀行に問い合わせるよう促されます。カートは保持されるため、購入者は再試行できます。新しい試行ごとに独自の SimplePay 参照番号が割り当てられます：PS、カート番号、試行番号（例：PS123-1、PS123-2）。

SimplePay が決済を開始できない場合、購入者には The SimplePay payment could not be started. Please try again or choose another payment method. と表示されます。カートの通貨に加盟店アカウントがない場合のメッセージは SimplePay is not available for the currency of this order. Please choose another payment method. です。技術的な理由はログに書き込まれます。

IPN は、ショップがメンテナンスモードの間も機能し、ショップの国別制限にはブロックされません。

本モジュールは、SimplePay のページで決済されるカードによる 1 回限りの決済のみに対応しています。保存済みカードやワンクリック決済、定期購読や定期課金、オーソリとキャプチャの分離には対応していません。

注文と返金

注文ステータス

まだ注文はありません: 購入者は SimplePay に移動しましたが、まだ支払っていない、決済に失敗した、キャンセルされた、タイムアウトした、または SimplePay がまだ決済を確認していません。カートだけが存在します。

Payment accepted or Delivered: 決済が確認されました。ステータスは Order Status After Payment に従います。決済は SimplePay の取引 ID とともに記録され、メモには取引 ID と、決済を確認したのが IPN かステータス照会かが表示されます。

SimplePay payment on hold: 決済が開始された後にカート合計または通貨が変更されたため、支払われた金額が注文と一致しません。決済は記録されません。メモには両方の金額が表示されます。注文を確認して処理するか、SimplePay の加盟店管理画面で決済を返金してください。その後、同じカートの別の試行が正しい金額で支払われた場合、注文は支払い済みのステータスに移行します。

Refunded: モジュールを通じて、決済の全額が返金されました。

支払い済み、返金済み、または配達済みの注文は、遅れて届いた IPN によって再オープンされることはありません。すでに支払い済みの注文に対して 2 回目の決済が成功しても、注文は変更されません。メモで、SimplePay の管理画面で確認し、重複している場合は返金するよう求められます。

SimplePay 決済ブロック

注文画面には SimplePay payment ブロックが表示され、取引 ID、注文参照番号（orderRef）、加盟店アカウントとモード、SimplePay のステータス、支払い済み金額と返金済み金額、サンドボックスの決済を示す Sandbox バッジ、カートの決済試行（複数回あった場合）、返金履歴、注文の SimplePay notes が表示されます。

返金

SimplePay payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via SimplePay (OTP) をクリックします。Refund this amount via SimplePay? This cannot be undone. という確認に応答してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。Modules のページへのアクセスは必要ありません。HUF の返金は整数のフォリントでなければなりません。返金は、注文を支払った SimplePay の取引に対して、その取引の金額と通貨で、その決済の加盟店アカウントとモード（サンドボックスまたは本番）を使って送信されるため、そのアカウントが設定に残っている必要があります。SimplePay が返金を受け付けなかった場合、ブロックにエラーが表示され、返金は記録されません。返金に成功すると、返金履歴とメモに、SimplePay の返金取引 ID と（入力した場合は）理由が追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。金額の不一致の後で保留になった注文は、ブロックから返金できません。SimplePay の加盟店管理画面で返金してください。

本モジュールはクレジットメモを作成しません。注文画面の標準の PrestaShop の返金ボタンでは、SimplePay を通じて返金は行われません。SimplePay の加盟店管理画面で行った返金は PrestaShop には同期されません。手動で記録してください。

ライセンスキー

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

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

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

トラブルシューティング

SimplePay がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、カートの通貨が HUF、EUR、USD のいずれかであること、そしてその通貨について現在のモードで Merchant ID と Secret key があることを確認してください。Sandbox mode がオンの間はサンドボックスのアカウント、オフの間は本番のアカウントです。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループに対して許可されていることも確認してください。

決済は完了したが、注文が作成されなかった: IPN がショップに届いていません。SimplePay の加盟店管理画面で、使用している加盟店アカウント（本番またはサンドボックス、カートの通貨に応じて）の IPN URL を確認してください。設定画面に表示された URL と完全に一致している必要があり、サーバーはインターネットから到達可能でなければなりません。注文は、購入者が決済後にショップへ戻ったときにも作成されます。

IPN が Invalid signature と応答する: IPN が、設定にない加盟店アカウントを指定している、その Secret key が誤っている、または決済とは別のモードのアカウントで署名されています。MERCHANT と SECRET KEY は、SimplePay の加盟店管理画面に表示されたとおりに正確に入力してください。SimplePay は未確認の IPN を再送します。

IPN が Order not found または Unknown transaction と応答する: この IPN は、このショップが開始していない決済に対するものです。何も変更されません。

IPN が Busy, retry と応答する: カートが同時に別のリクエストによって処理されていた、または注文を作成できなかった（たとえばモジュールが無効になっていた）ことを意味します。SimplePay は IPN を再試行します。理由はログに書き込まれます。

購入者に The SimplePay payment could not be started と表示される: モジュールのページにある Log 欄を確認してください。シークレットキーが誤っている場合、Invalid response signature from SimplePay. Check the secret key of the merchant account. が表示されます。SimplePay のエラーは、そのエラーコードとともにログに記録されます。

サンドボックスと本番を切り替えた後: 新しい決済は新しいモードのアカウントを使用します。それ以前に開始された決済は、開始時の加盟店アカウントとモードを維持します。その IPN、ステータス照会、返金は、そのアカウントを使用します。そのような決済が未完了の間、または返金される可能性がある間は、古いモードのアカウントを設定に残しておいてください。

決済後に注文が SimplePay payment on hold になる: SimplePay payment ブロックのメモを確認してください。決済が開始された後に、カート合計または通貨が変更されています。注文を処理するか、SimplePay の加盟店管理画面で決済を返金してください。

返金に失敗する: ブロックのメッセージを確認してください。SimplePay refunds in HUF must be whole amounts. は、HUF の金額に小数点以下の桁があったことを意味します。メッセージに、この決済の加盟店アカウントが設定されていないと書かれている場合は、決済時に使用したアカウント（通貨とモード）を入力し直してください。SimplePay が別の金額を返金していた場合、メッセージは SimplePay の管理画面で返金を確認するよう求めます。

アンインストール

Modules > Module Manager に移動し、VibeFox SimplePay Gateway の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete Data on Uninstall がオンの場合、ゲートウェイの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。SimplePay の取引と返金、および注文ステータス SimplePay payment on hold は常に保持されるため、以前に支払われた注文は、再インストール後も返金できます。既存の注文は、決済のメモと取引 ID を保持します。

SimplePay は、その所有者の商標です。本モジュールは SimplePay による提携や推奨を受けていません。