VibeFox Satispay for PrestaShop — ヘルプ

動作要件

PrestaShop: 8.0 から 9.x。

PHP: OpenSSL 拡張機能を含む 8.0 以降。古い PHP バージョンや OpenSSL のない環境では、モジュールはインストールできません。

通貨: EUR。Satispay はユーロのみで請求するため、カートの通貨が EUR でない場合、この支払い方法は表示されません。

Satispay アカウント: Satispay Business アカウント。API キーをコピーする必要はありません。モジュールは、Satispay Business Dashboard で作成する 1 回限りの有効化コードで接続します（「設定」を参照）。テスト用には、Satispay for developers からリクエストできる Satispay サンドボックスアカウントが必要です。

公開ショップ: 決済の状態が変わったときに Satispay がショップを呼び出せるよう、ショップがインターネットから到達可能である必要があります。このために Satispay 側で設定する必要はありません。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後で確認する場合は、モジュール一覧で VibeFox Satispay Gateway を探して Configure をクリックします。

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

4. 環境を選択します。テストでは Sandbox Mode をオンにし、実際の決済ではオフのままにします。

5. その環境の有効化コードを Activation Code に貼り付け、Save をクリックします。その後、Status に Connected と Key ID が表示されます。

6. Enable/Disable をオンにして Save をクリックします。サンドボックスで決済をテストし、その後 Sandbox Mode をオフにして、本番環境の有効化コードで本番環境を接続します。

インストール時に、モジュールは注文ステータス Satispay payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。これらは Payment > Preferences で制限できます。そこで、このモジュールがユーロに対して許可されている必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Satispay Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。

チェックアウト

支払い方法の一覧でお客様に表示される内容です。

Enable/Disable: Enable Satispay payment で支払い方法のオン・オフを切り替えます。デフォルト: off。

Title: チェックアウトで表示される支払い方法の名前です。注文に保存される支払い方法名にもなります。デフォルト: Satispay。必須。

Description: チェックアウトで支払い方法の下に表示される文章です。デフォルト: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

Satispay 接続

Status: 両方の環境の状態です。例として、Key ID 付きの Live: Connected、または Sandbox: Not connected と、現在使用中の環境が表示されます。使用中の環境が接続されていない間、このフィールドには Satispay is hidden at checkout until the environment in use is connected. と表示されます。

Sandbox Mode: Satispay のサンドボックス（テスト）環境を使用します。サンドボックスの決済には課金されません。デフォルト: off。サンドボックスと本番環境はキーが別々なので、それぞれ対応する環境の有効化コードで接続してください。サンドボックスを使用している間、お客様には支払い方法の下に Sandbox mode: no real money is charged. と表示されます。

Activation Code: 上で選択した環境を接続するには、新しい 6 文字の有効化コードを貼り付けて Save をクリックします。本番環境のコードは Satispay Business Dashboard の Online shop セクションで発行されます。サンドボックスのコードは Satispay サンドボックスアカウントに付属します。コードは 1 回だけ使用され、保存されません。現在の接続を維持する場合は、フィールドを空のままにしてください。

コードを付けて保存すると、モジュールは RSA 鍵ペアを作成し、公開鍵とコードを Satispay に送信します。そして、Key ID とその環境の鍵をショップの設定に保存します。秘密鍵は決して表示されません。成功すると、ページには例えば Satispay Live connected. Key ID: と ID が表示されます。Satispay がコードを拒否した場合、ページには Satispay activation failed: と Satispay からのメッセージが表示され、コードがこの環境のものであり、まだ使用されていないかを確認するよう求められます。文字と数字以外の文字を含むコードは、何も送信される前に拒否されます。ある環境に新しいコードを保存すると、その環境の以前の接続は置き換えられます。

支払い通知

Satispay 側で設定する必要はありません。すべての決済には独自のコールバック URL があり、決済が変わると Satispay がそれを呼び出します。モジュールは、注文を作成または変更する前に、決済を Satispay API から再取得します。Callback URL フィールドには、この URL の例が表示されます。フレンドリー URL を使用している場合、次のような形になります：https://your-shop/module/wcp_satispay_gateway/callback?id_cart={cart}&payment_id={uuid}。先頭に /en/ などの言語コードが付くこともあります。この URL はインターネットから到達可能である必要があります。前段にベーシック認証を設けないでください。コールバックは、ショップがメンテナンスモードでも動作し、ショップの国制限の影響も受けません。

詳細設定

Debug log: API の呼び出しと決済イベントを、モジュールフォルダー内の logs/satispay_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。キーとお客様のデータは記録されません。エラーは、このオプションがオフでも常に記録されます。デフォルト: off。

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

Delete data on uninstall: オンの場合、モジュールをアンインストールすると、設定、両方の環境の Satispay キー、ログが削除されます。注文用に保存された Satispay の決済と返金、および注文ステータス Satispay payment on hold は、常に保持されます。デフォルト: off。

チェックアウト

支払いステップで、お客様は支払い方法（デフォルトは Satispay）を選択し、注文を確定します。モジュールは、カートの合計金額をユーロで指定した Satispay 決済を作成します。参照番号としてカート番号が使われ、お客様は Satispay の決済ページに移動します。パソコンでは、お客様は Satispay アプリで QR コードをスキャンします。スマートフォンでは、アプリで支払いを確定します。この時点ではまだ注文は存在しません。

支払い後、お客様はショップに戻ります。注文が支払い済みになるのは、Satispay が決済を確定した後だけです。モジュールは Satispay API から決済を取得し、それがこのカートのために作成されたことを確認し、そのステータス、金額（セント単位）、通貨をカートと照合します。これは、Satispay がコールバック URL を呼び出したときと、お客様が戻ったときの両方で行われ、先に届いた方が処理されます。その後、注文が作成され、お客様には標準の注文確認ページが表示されます。お客様が戻った時点で Satispay がまだ決済を確定していない場合、Payment confirmation ページに Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. と Check again ボタンが表示されます。コールバックが届き次第、注文が作成されます。

お客様が支払わずに Satispay のページを離れた場合、モジュールは Satispay でその決済をキャンセルするため、放棄されたページはもう支払うことができません。お客様はチェックアウトに戻り、Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. というメッセージが表示されます。お客様がアプリで決済を拒否した場合にも、同じメッセージが表示されます。カートは保持されます。

同じカートに対して新しい Satispay 決済を作成する前に、以前の決済が確認されます。保留中の決済は Satispay でキャンセルされます。以前の決済がすでに支払い済みであれば、注文はその決済で作成され、2 回目の支払いは行われません。

決済を開始できない場合、お客様はチェックアウトに留まり、短いメッセージが表示されます。ショップが接続されていない場合、または Satispay がキーを拒否した場合は Satispay is not available at the moment. Please choose another payment method.、その他のエラーの場合は Unable to create the Satispay payment. Please try again or choose another payment method. と表示されます。理由はログに記録されます。

このモジュールが受け付けるのは、ユーロ建ての 1 回限りの支払いのみです。サブスクリプション、保存済みの支払い方法、事前承認、食事券には対応していません。保留中の決済を定期的に確認する仕組みはありません。Satispay からのコールバックもお客様の戻り操作も、ショップに届かなければ注文は作成されず、その決済は Satispay Dashboard でのみ確認できます。

注文と返金

注文ステータス

No order yet: お客様は Satispay に移動したものの、まだ支払っていないか、Satispay がまだ決済を確定していません。存在するのは、カートとモジュールの Satispay 決済だけです。

Payment accepted: 決済が確定しました。決済は Satispay の決済 ID をトランザクション ID として記録され、メモには Satispay の決済、金額、確認方法（callback、redirect or checkout）が表示されます。

Satispay payment on hold: Satispay が、カートの合計と異なる金額または通貨を報告した場合（例えば、決済の開始後に別のタブでカートが変更された場合）、または注文がキャンセルされた後に決済が受理された場合です。受け取った金額は注文に記録され、メモで説明されます。Satispay Dashboard で決済を確認したうえで、注文を処理するか、決済を返金してください。同じカートについて、正しい金額の別の決済が後から受理された場合、注文は Payment accepted に移行します。

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

すでに支払い済みの注文に対して 2 回目の決済が受理された場合、注文は変更されません。メモで、Satispay Dashboard から重複した決済を返金するよう求められます。繰り返しの確認によって、キャンセルされた注文や返金済みの注文が再び開かれることはありません。

Satispay 決済ブロック

注文ページには Satispay payment ブロックが表示されます。このブロックには、Satispay 決済 ID、そのステータス、支払い済み金額と返金済み金額、サンドボックス決済用の Sandbox バッジ、返金履歴、各支払い試行とその環境を示す Satispay payments of this cart の一覧、そして注文の Satispay notes が含まれます。

返金

Satispay payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Satispay をクリックします。Refund this amount through Satispay? This cannot be undone. の確認に同意してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。Modules のページへのアクセスは必要ありません。返金額は、Satispay がその決済で請求した金額までに制限されています。そのため、金額の不一致が発生した後は、注文合計ではなく、お客様が実際に支払った金額まで返金できます。返金は決済が行われた環境（本番またはサンドボックス）に送信されるため、その環境が引き続き接続されている必要があります。返金は、Satispay が受け付けた場合にのみ完了とみなされます。成功した返金は、Satispay の返金 ID と理由とともに返金履歴とメモに追加されます。Satispay が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。

このモジュールはクレジット票（credit slip）を作成しません。注文ページにある PrestaShop の標準の返金ボタンは、Satispay を通じて返金を行いません。Satispay Dashboard で行った返金は PrestaShop に記録されません。必要に応じて、注文を手動で更新してください。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Satispay が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、使用中の環境が接続されていること（Status フィールドにその環境の Connected が表示されること）、カートの通貨が EUR であることを確認してください。Payment > Preferences で、このモジュールがユーロ、お客様の国、お客様のグループに対して許可されていることも確認してください。

決済は完了したが、注文が作成されていない: 注文は、Satispay がショップを呼び出したとき、またはお客様が戻ったときに作成されます。ショップがインターネットから到達可能であること、コールバック URL の前段にベーシック認証がないことを確認し、Debug log をオンにして Log フィールドでコールバックを確認してください。決済は Satispay Dashboard で確認できます。

コールバックが Payment status unavailable, retry later. または Not configured. を返す: モジュールが Satispay から決済を取得できなかったか、決済の環境が接続されていません。注文は変更されません。Satispay は再度呼び出します。接続状態とログを確認してください。

コールバックが Busy, retry later. を返す: 同じ瞬間に、別のリクエストによってカートが確認されていたか、注文を作成できませんでした（例えば、モジュールが無効になっている場合）。Satispay は再度呼び出します。ログに理由が表示されます。

コールバックが Unknown payment. または Missing or invalid payment_id. を返す: その決済は、このショップがこのカートのために作成したものではないか、リクエストが Satispay のコールバックではありません。何も変更されません。

有効化に失敗する: 有効化コードは 1 回だけ使用できます。Sandbox Mode で選択した環境のコードであることを確認してください（本番環境には本番のコード、サンドボックスにはサンドボックスのコード）。新しいコードを生成し、もう一度保存してください。ページに RSA 鍵ペアを生成できなかったと表示される場合は、ホスティング会社に PHP の OpenSSL 拡張機能を有効にするよう依頼してください。Satispay に接続できない場合は、サーバーから外向きの HTTPS 接続を開けることを確認してください。

サンドボックスから本番環境に切り替えた後、チェックアウトから Satispay が消えた: サンドボックスと本番環境では、キーが異なります。Sandbox Mode をオフにした状態で、本番の有効化コードを貼り付けて保存してください。

お客様に This payment method is not available. と表示される: この支払い方法は、カートに対して許可されていません（Payment > Preferences の国、通貨、または顧客グループ）。無効になっているか、使用中の環境が接続されていません。

支払い後に注文が Satispay payment on hold になる: Satispay payment ブロックのメモを確認し（注文ステータスを参照）、Satispay Dashboard で決済を確認してから、注文を処理するか、決済を返金してください。

環境が接続されなくなったため、返金に失敗する: 決済は本番環境またはサンドボックスで行われましたが、その環境には現在キーがありません。有効化コードで再接続するか、Satispay Dashboard から決済を返金してください。

Satispay did not accept the refund と表示されて返金に失敗する: Satispay が accepted 以外のステータスを返しました。PrestaShop は返金を記録せず、その旨がメモに記載されます。Satispay Dashboard で確認してください。

アンインストール

Modules > Module Manager に移動し、VibeFox Satispay Gateway の横にあるメニューを開いて Uninstall を選びます。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、設定、両方の環境の Satispay キー、ログが削除されます。オフの場合、後で再インストールできるよう、すべての設定とキーが保持されます。注文用に保存された Satispay の決済と返金、および注文ステータス Satispay payment on hold は常に保持されるため、環境が再接続されれば、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いメモとトランザクション ID を保持します。

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