VibeFox Satispay for OpenCart — ヘルプ

要件

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

PHP： OpenSSL 拡張が有効な 8.0 以降。本拡張は RSA 鍵の作成に OpenSSL を使用します。

通貨： EUR。Satispay はユーロのみで決済します。EUR 通貨は System > Localisation > Currencies で有効にする必要があり、支払い方法は顧客が EUR を選択しているときにのみ表示されます。

Satispay アカウント： Satispay Business アカウント。API キーをコピーする必要はありません。本拡張は、Satispay Business Dashboard で生成するワンタイムのアクティベーションコードを使って接続します（Configuration を参照）。テストには Satispay のサンドボックスアカウントが必要です。これは Satispay の開発者向けに申請してください。

公開ストア： Satispay が決済状況の変化時にストアを呼び出せるよう、ストアはインターネットからアクセスできる必要があります。このために Satispay 側で設定する項目はありません。

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

インストール

このダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。中には README.txt、OpenCart 3 用のパッケージ wcp_satispay_gateway-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ wcp_satispay_gateway.ocmod.zip が含まれています。ご利用の OpenCart のバージョンに合ったパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

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

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

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

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

5. その環境のアクティベーションコードを Activation Code に貼り付け、Save をクリックします。すると Status に Key ID とともに Connected と表示されます。

6. Enable/Disable をオンにして Save をクリックします。サンドボックスでテスト決済を行い、その後 Sandbox Mode をオフにして、本番環境を本番用のアクティベーションコードで接続します。

OpenCart 4

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

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

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

4. ライセンスキーを入力し、環境を選択して、アクティベーションコードで接続します。手順は OpenCart 3 の手順 3 〜 6 と同じです。設定ページとそのフィールドは両方のバージョンで同じです。異なるのはコールバック URL だけです（支払い通知を参照）。

新規インストール直後は、支払い方法がオフで、本番環境が選択された状態になっています。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Satispay Gateway > Edit。設定の各セクションは左側に表示されます。一覧の下にある Save ボタンで、ページ全体を保存します。設定の上には、支払い方法が有効になっているのに使用中の環境が接続されていない場合（その場合、支払い方法はチェックアウトで非表示になります）や、ストアの既定通貨が EUR でない場合（その場合、支払い方法は顧客が EUR を選択しているときにのみ表示されます）に、ページが警告を表示します。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時、Title は 1 〜 128 文字である必要があり、Sort Order は整数（負の数も可）である必要があります。Total は 0 以上の数値である必要があり、ジオゾーンと注文ステータスが存在している必要があります。値が正しくない場合は、何も保存されず、アクティベーションコードも送信されません。

チェックアウト

Enable/Disable: Enable Satispay payment は支払い方法をオンまたはオフにします。Default: off.

Title: チェックアウトで顧客に表示される支払い方法の名前です。注文にも支払い方法名としてこの名前が保存されます。Default: Satispay. 必須、128 文字以内。

Description: Confirm Order のステップで、確認ボタンの上に顧客に表示される文章です。Default: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

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

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

Total: Satispay を提供するために注文が達している必要がある、ストアの既定通貨でのチェックアウト合計金額です。0 以上の数値で入力します。空欄にすると、どの金額でも Satispay を提供します。

Satispay の接続

Status: 両方の環境の状態を示します。たとえば Key ID 付きの Live: Connected や Sandbox: Not connected、そしてどちらの環境が in use かを表示します。使用中の環境が接続されていない間、この欄には Satispay is hidden at checkout until the environment in use is connected. と表示されます。

Sandbox Mode: Satispay のサンドボックス（テスト用）環境を使用します。サンドボックスの支払いには料金が発生しません。Default: off. サンドボックスと本番では鍵が別々です。それぞれの環境を、その環境のアクティベーションコードで接続してください。サンドボックスを使用している間、顧客には Confirm Order のステップで Sandbox mode: no real money is charged. と表示されます。

Activation Code: 上で選択した環境を接続するには、新しい 6 文字のアクティベーションコードを貼り付けて Save をクリックします。本番用のコードは Satispay Business Dashboard の Online shop セクションで生成します（この欄からそのページへのリンクがあります）。サンドボックス用のコードは Satispay のサンドボックスアカウントに付属します。コードは一度だけ使用され、保存されません。現在の接続を維持する場合は、この欄を空欄のままにします。

コードを入力して保存すると、先に設定が保存されます。次に、拡張機能が RSA 鍵ペアを作成し、公開鍵とコードを Satispay に送信して、Key ID と使用中の環境の鍵を保存します。秘密鍵は表示されず、エクスポートもされません。成功すると、ページには例えば Satispay Live connected. Key ID: とその後に ID が表示されます。Satispay がコードを拒否した場合は、Satispay activation failed: と Satispay からのメッセージが表示され、そのコードがこの環境のものであり、まだ使用されていないかを確認するよう求められます。現在の接続はそのまま維持されます。4 〜 64 文字の英数字でないコードは、何も送信される前に拒否されます。ある環境に新しいコードを保存すると、その環境の以前の接続は置き換えられます。

支払い通知

Satispay 側で設定することはありません。すべての支払いには独自のコールバック URL があり、支払いの状況が変わると Satispay がその URL を呼び出します。拡張機能は、注文を変更する前に Satispay API から支払いを読み直します。Callback URL 欄には、この URL の例が表示されます。OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_satispay_gateway/callback&satispay_p_order={order}&payment_id={uuid} のような形式で、OpenCart 4 では https://your-store/index.php?route=extension/wcp_satispay_gateway/payment/wcp_satispay_gateway.callback&satispay_p_order={order}&payment_id={uuid} のような形式です。URL は OpenCart をインストールしたストアフロントのアドレスから作成されます。この URL はインターネットからアクセスできる必要があり、その前にファイアウォールやベーシック認証を設けてはいけません。OpenCart のメンテナンスモードでもブロックされません。コールバックがストアに届かない場合、注文は顧客が戻ったときに確定されます。

注文

OpenCart は Confirm Order のステップで、ステータスのない注文（欠落注文、missing order）を作成します。注文がステータスを得るのは、Satispay が支払いを受け付けた後だけです。以下の各欄には、OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment: 支払いが受け付けられた後に設定されるステータスです。Default: Processing.

Satispay Payment On Hold Status: 入金はありましたが、注文の確認が必要な状態です（Order statuses を参照）。Default: Pending。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

Refunded Status: 注文ページから支払いが全額返金された後に設定されます。Default: Refunded.

詳細設定

Debug log: API 呼び出しと支払いイベントを、OpenCart のログフォルダ（storage/logs）にある satispay_p_debug.log.php に書き込みます。このファイルは Web から開くことができず、5 MB に達すると satispay_p_debug.old.log.php に移動されます。鍵、アクティベーションコード、顧客データは記録されません。この設定がオフでも、エラーは常に記録されます。Default: off.

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

Delete data on uninstall: オンにすると、拡張機能のアンインストール時にゲートウェイの設定、両方の環境の Satispay 鍵、ログが削除されます。注文に保存された Satispay の支払いと返金は、常に保持されます。Default: off.

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

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

Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。Satispay の接続は維持されます。

チェックアウト

Payment Method のステップで、顧客は支払い方法を選択します（既定では Satispay）。Confirm Order のステップでは、顧客に、あなたの説明文と You will be redirected to the Satispay page: scan the QR code with the Satispay app or confirm the payment on your phone. という注意書きが表示されます。OpenCart はこのステップで注文を作成しますが、まだステータスはありません。顧客が Confirm Order をクリックすると、拡張機能は注文番号を参照として、注文合計額をユーロで指定した Satispay の支払いを作成し、顧客を Satispay の支払いページへ移動させます。パソコンでは、顧客は Satispay アプリで QR コードを読み取ります。スマートフォンでは、顧客はアプリ内で支払いを確認します。OpenCart 4 では、顧客は支払い方法のブロックにある Choose ボタンを使い、Payment method options ウィンドウで支払い方法を選択して、チェックアウトページ下部の Confirm Order をクリックします。

支払い後、顧客はストアに戻ります。注文は、Satispay が確認した後にのみ支払い済みとしてマークされます。拡張機能は Satispay API から支払いを読み取り、その支払いがこの注文のために作成されたものかを確認したうえで、そのステータス、金額（セント単位）、通貨を注文と照合します。これは、Satispay がコールバック URL を呼び出したときと、顧客が戻ったときの両方で行われ、先に起きたほうが処理されます。その後、注文は OpenCart の標準的な方法でステータスを得て、通常の注文メールと在庫の更新が行われ、顧客は OpenCart の注文完了ページを見ます。顧客が戻った時点で 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. というメッセージとともにチェックアウトに戻ります。顧客がアプリで支払いを拒否した場合も、同じメッセージが表示されます。カートは保持されます。

Confirm Order のステップが表示されるたびに、OpenCart 3 は新しい注文を作成します。OpenCart 4 では、チェックアウトの注文を 1 つ保持して更新するため、キャンセルされた支払いの後は、同じ注文に新しい Satispay の支払いが行われます。新しい Satispay の支払いを作成する前に、カートの以前の支払いが確認されます。保留中の支払いは Satispay でキャンセルされ、すでに支払い済みのものがあれば、その注文を確定させます。2 回目の支払いは行われず、顧客は直接完了ページに進みます。

OpenCart 4 では、キャンセルされた支払いに関するメッセージがチェックアウトページの上部に表示されます。チェックアウトの注文がその間にストアによって閉じられた場合（たとえばキャンセルまたは返金）、あるいは注文がすでに支払い済みでも、数量の変更を含めてその後カートが変わった場合、顧客は、チェックアウトページの上部に表示される Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. というメッセージとともにチェックアウトに戻されます。次の Confirm Order では新しい注文が支払われます。

支払いを開始できない場合、顧客はConfirm Order のステップにとどまり、ボタンの上に短いメッセージが表示されます。Satispay がキーを拒否した場合は Satispay is not available at the moment. Please choose another payment method.、注文が別の通貨の場合は Satispay supports EUR currency only.、その他のエラーの場合は Unable to create the Satispay payment. Please try again or choose another payment method. です。理由はログに記録されます。

コールバックと顧客の戻りは、ストアがメンテナンスモードの間も機能します。OpenCart 3 は支払い拡張機能のリクエストを通過させ、OpenCart 4 では拡張機能がそのためのスタートアップアクションを追加します。

本拡張機能は、ユーロによる一回限りの支払いのみを扱います。定期購読、保存済みの支払い方法、事前承認、食事券には対応していません。保留中の支払いを定期的に確認する仕組みはありません。Satispay のコールバックも顧客の戻りも、ストアに届かない場合、注文はステータスのないままになり、支払いは Satispay Dashboard で確認できます。

注文と返金

注文ステータス

No status (missing order): 顧客は Satispay に送られましたが、まだ支払っていないか、Satispay がまだ支払いを確認していません。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定したときにのみ表示されます。キャンセルされた Satispay の支払いは注文をステータスのないままにし、顧客は再度支払うことができます。

Order Status After Payment (default Processing): 支払いが受け付けられました。メモには、Satispay の支払い、金額、確認方法（コールバック、リダイレクト、チェックアウト）が表示されます。

Satispay Payment On Hold Status (default Pending): Satispay が注文合計と異なる金額または通貨を報告したか、注文が別のステータス（例：キャンセル）になった後に支払いが受け付けられました。メモにその理由が説明されます。Satispay Dashboard で支払いを確認したうえで、注文を発送するか、支払いを返金してください。同じカートの正しい金額の別の支払いが後で受け付けられた場合、注文は Order Status After Payment に移ります。

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

すでに支払い済みの注文、または同じカートの別の注文に対して 2 回目の支払いが受け付けられた場合、支払い済みの注文は変更されません。メモで、重複した支払いを Satispay Dashboard から返金するよう案内されます。

メモは、顧客には表示されない注文の History のエントリです。

VibeFox Satispay Gateway tab

Sales > Orders で、Satispay で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox Satispay Gateway タブには、サンドボックスの支払いには Sandbox ラベル付きの Satispay payment ID、支払いの Status、Paid / refunded の金額、返金フォーム、Refunds の履歴、各支払い試行とその注文および環境を含む Satispay payments of this cart の一覧、そして注文の Satispay notes が表示されます。このタブは、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

VibeFox Satispay Gateway タブで Amount を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて Reason (optional) を入力して、Refund via Satispay をクリックします。確認の質問 Refund this amount through Satispay? This cannot be undone. に同意してください。全額返金と部分返金に対応しています。拡張機能を変更する権限が必要です（System > Users > User Groups で設定します）。返金額は、Satispay がその支払いで請求した金額に制限されます。そのため、金額の不一致が起きた後は、注文合計ではなく、顧客が実際に支払った金額まで返金できます。返金は、支払いが行われた環境（本番またはサンドボックス）に送信されるため、その環境は引き続き接続されている必要があります。返金は、Satispay が受け付けた場合にのみ完了とみなされます。成功した返金は、Satispay の返金 ID と理由とともに、履歴とメモに追加されます。Satispay が返金を受け付けない場合、タブにエラーが表示され、返金は記録されません。全額返金では、顧客に通知せず、商品を在庫に戻さずに、注文を Refunded Status に設定します。これは手動のステータス変更と同じです。部分返金ではステータスは変わりません。返金は、Satispay が支払いを受け付けた後に利用できます。

Sales > Returns での商品の返品では、Satispay を通じて返金されることはありません。Satispay Dashboard で行った返金は、OpenCart には記録されません。必要に応じて注文を手動で更新してください。

License key

本拡張機能は、vibefox.net で取得した VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox Satispay Gateway は、Extensions > Extensions > Payments > VibeFox Satispay Gateway > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後、このブロックにはキーがマスクされた形で表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ボタン Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）が表示されます。その下には、Product: opencart-payment-satispay の行と、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 のアカウントで枠を解放してください。

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

トラブルシューティング

Satispay がチェックアウトに表示されない： ライセンスが有効であること、Enable/Disable がオンであること、使用中の環境が接続されていること（Status 欄にそのための Connected が表示されます）、顧客が EUR を選択していることを確認してください。また、支払い住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

支払いは完了したが、注文のステータスがない： 注文は、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. と表示される： チェックアウトが注文と一致しなくなったか、その間に支払い方法がオフにされました。顧客はチェックアウトを再読み込みします。

支払い後に注文がレビューのステータスになっている： VibeFox Satispay Gateway タブのメモを読み（Order statuses を参照）、Satispay Dashboard で支払いを確認してから、注文を発送するか、支払いを返金してください。

タブに返金フォームがない： タブに理由が表示されます。注文に受け付けられた Satispay の支払いがない、全額返金済みである、ユーザーグループに拡張機能を変更する権限がない、または支払いの環境がもう接続されていない、のいずれかです。

環境が接続されていないため返金に失敗する： 支払いは本番またはサンドボックスで行われましたが、その環境にはもう鍵がありません。アクティベーションコードで再接続するか、Satispay Dashboard から支払いを返金してください。

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

アンインストール

Extensions > Extensions を開き、種類で Payments を選択して、VibeFox Satispay Gateway の隣にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します：Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。OpenCart 4 では、拡張機能のイベントとそのスタートアップアクション（メンテナンスモードでもコールバックと顧客の戻りを通過させるもの）も削除されます。Delete data on uninstall がオンの場合、その他のゲートウェイ設定（タイトル、説明、サンドボックスモード、ログ）、両方の環境の Satispay 鍵、ログも削除されます。オフの場合は、後で再インストールするために保持され、Satispay の接続も含まれます。注文に保存された Satispay の支払いと返金は常に保持されるため、以前に支払われた注文は、環境が再接続されれば再インストール後も返金できます。既存の注文には支払いのメモが残ります。

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

Satispay は、その所有者の商標です。本拡張機能は Satispay と提携しておらず、Satispay による承認もありません。