VibeFox Square for PrestaShop — ヘルプ
要件
PrestaShop：8.0 から 9.x。
PHP：8.0 以降。モジュールは古い PHP バージョンではインストールできません。
通貨：カートの通貨は、Square ロケーションの通貨と同じである必要があります：USD、CAD、AUD、JPY、GBP、EUR のいずれか。その他の通貨の場合、チェックアウトで支払い方法は表示されません。Square は、米国、カナダ、オーストラリア、日本、英国、アイルランド、フランス、スペインの販売者に対応しています。
Square アカウント：Square Developer Dashboard でアプリケーションを作成する必要があります。そこから Application ID と Access Token（Credentials ページ）、Location ID（Locations ページ）をコピーします。Sandbox と Production では値が別々です。Webhook は不要です：モジュールは Square の応答から直接、支払い結果を取得します。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ使用できます。
インストール
1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後で VibeFox Square Gateway をモジュール一覧から探して Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. Sandbox Mode をオンのままにして、Sandbox 用の Application ID、Access Token、Location ID を入力します（設定を参照）。Save をクリックすると、モジュールが Square で認証情報を確認します。
5. Enable/Disable をオンにして保存し、Square のサンドボックステストガイドにあるテストカードで支払いをテストします。その後 Sandbox Mode をオフにし、本番用の認証情報を入力して再度保存します。
インストール時に、モジュールは注文ステータス Square payment on hold を作成します。PrestaShop は、新しい支払いモジュールに対して、インストール時点で有効な通貨、国、顧客グループを割り当てます。これらを確認し、後から追加した国は Payment > Preferences で選択してください。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Square Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。Sandbox モードがオンの間、フィールドの上には Square Gateway は現在 SANDBOX モードです。実際の請求は行われません。 と表示されます。Square が有効なのに選択中のモードの Application ID、Access Token、Location ID のいずれかがない場合（支払い方法はチェックアウトで非表示になります）、Square がショップの既定の通貨を処理できない場合、または Square ロケーションの通貨がそれと異なる場合には、警告が表示されます。
保存すると、モジュールは選択中のモードの認証情報を Square で確認します。設定は常に保存されます。Square が Access Token を拒否した場合、そのトークンに対して Location ID が見つからない場合、認証情報を確認できなかった場合、またはロケーションの通貨がショップの通貨と異なる場合には、警告が表示されます。Square は、ロケーションの通貨でのみ請求できます。モジュールは確認済みロケーションの通貨を記憶し、それ以外の通貨のカートでは支払い方法を非表示にします。また、sandbox の Application ID が live モードで使われている場合、またはその逆の場合にも警告します。
Square
Enable/Disable：Enable Square Payment Gateway は支払い方法を有効または無効にします。デフォルト：off。
Title：チェックアウトで購入者に表示される支払い方法のタイトルです。注文に保存される支払い方法名にもなります。デフォルト：Credit / debit card。必須。
Description：チェックアウトで購入者に表示される支払い方法の説明です。デフォルト：Pay securely with your credit or debit card via Square。サンドボックスモードでは (SANDBOX MODE) が追加されます。
Square アカウント
Square Developer Dashboard を開き（このセクションにはリンクがあります）、アプリケーションを選択して、Credentials ページから Application ID と Access token（Sandbox と Production では値が別々です）を、Locations ページから Location ID をコピーします。ロケーションの通貨はショップの通貨と一致している必要があります。ページには、選択中のモードの認証情報フィールドだけが表示されます。Sandbox Mode がオンの間は sandbox のフィールド、オフの間は live のフィールドです。両方のセットは保存されたままになります。
Sandbox Mode：支払いは Square のサンドボックスに送られ、実際のお金は請求されません。Square のテストカードを使用してください。デフォルト：on。
Sandbox Application ID：Square の sandbox 用 Application ID です（sandbox-sq0idb- で始まります）。
Sandbox Access Token：Square の sandbox 用 Access Token です。
Sandbox Location ID：Square の sandbox 用 Location ID です。
Live Application ID：Square の本番用 Application ID です（sq0idp- で始まります）。
Live Access Token：Square の本番用 Access Token です。
Live Location ID：Square の本番用 Location ID です。
保存済みのアクセストークンは再び表示されません。フィールドは空のままで、保存済み — 保持するには空のままにしてください。 と表示されます。変更したい場合にのみ新しい値を入力してください。
Clear saved secrets：アクセストークンにチェックを入れて Save をクリックすると削除されます。空のフィールドは保存済みの値を保持します。
詳細設定
Debug log：エラーと警告は常に記録されます。オンにすると、すべてのリクエストとレスポンスも、カードデータやキーを除いて、モジュールフォルダ内の logs/wc_sqg_debug.log.php に記録されます。このファイルは Web からは開けません。デフォルト：off。
Log：ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Delete data on uninstall：オンの場合、モジュールをアンインストールすると、ゲートウェイの設定とログファイルが削除されます。注文に紐づく Square の支払いと返金、および注文ステータス Square payment on hold は常に保持されます。デフォルト：off。
チェックアウト
支払いの手順で、購入者は支払い方法（デフォルトは Credit / debit card）を選び、説明の下に表示される Square カードフォームにカード情報を入力します。注文を確定すると、カードはブラウザ内で購入者の本人確認（3-D Secure / SCA）を伴ってトークン化されます。カート合計、通貨、請求先住所が Square に渡され、購入者の銀行が確認を求める場合があります。ショップが受け取るのは 1 回限りのトークンだけです。
その後、モジュールはそのトークンを Square Payments API 経由で、カートの通貨によるカート合計として請求します。参照にはカート ID を使用し、カート番号とショップ名を含む Cart # の備考と、購入者のメールアドレスも送信されます。支払いは即時に売上確定されます。注文が支払い済みとマークされるのは、Square が確認した後だけです。Square の応答には、カート合計、通貨、カート ID、ロケーションが完全に一致する COMPLETED の支払いが示されている必要があります。その後、注文は Payment accepted で作成され、購入者には標準の注文確認ページが表示されます。そこには カード決済を受け付けました。 と、Square の領収書へのリンクが含まれます。支払いが COMPLETED でない場合、または値が一致しない場合は、注文は Square payment on hold で作成され、ページには カード決済を受け付け、確認中です。確認が完了次第、注文を更新します。 と表示されます。
カートごとに同時に実行される支払い試行は 1 回だけです。購入者が 2 回クリックしたり、2 つのタブで支払ったりした場合、2 回目の試行には この注文はすでに支払い処理中です。しばらく待ってから、メールを確認して再度お試しください。 と表示されます。リクエストは冪等です。同じカート、同じカードトークン、同じ金額では、2 回目の支払いが作成されることはなく、すでに注文があるカートが再度請求されることもありません。
Square から応答がない場合（ネットワークの問題、タイムアウト、サーバーエラー）、同じ冪等キーでリクエストが 1 回だけ再試行されます。それでも応答がない場合、モジュールは直ちに Square でこのカートの支払いを探します。見つかった場合は、その支払いで注文を作成します。支払いが見つからない場合、購入者はチェックアウトに留まり、支払いプロバイダーから確認を取得できませんでした。1 分ほど待ってから再度お試しください。カードがすでに請求されていた場合は、支払いが認識され、二重請求は行われません。 と表示されます。次の試行では、まず以前の支払いを再び探します。その確認のためにも Square に接続できない場合、注文は支払いなしで Square payment on hold として作成され、カードが請求された可能性があるという備考が付きます。確認ページには Square からカード決済の確認を取得できませんでした。再度お支払いいただく前に、メールとカードの利用明細をご確認いただくか、お問い合わせください。 と表示されます。
銀行がカードを拒否した場合、注文は作成されず、購入者はチェックアウトに留まり、Square のエラーコードに応じた短いメッセージが表示されます。例：カードが拒否されました。別のカードまたは支払い方法をご利用ください。、カードのセキュリティコード（CVV）が正しくありません。ご確認のうえ、再度お試しください。、または お使いの銀行で追加の認証（3-D Secure）が必要です。カードを再度入力し、認証を完了してください。 カートは保持され、購入者は別のカードで再度試すことができます。技術的な理由はログに記録されます。
本モジュールが対応しているのは、即時に売上を確定する 1 回払いのカード決済だけです。保存済みカードや顧客プロファイル、サブスクリプション、Apple Pay、Google Pay、Cash App Pay、Afterpay、ACH、Square ギフトカードには対応していません。オーソリのみの決済、Square の Webhook、Square との商品や在庫の同期にも対応していません。紛争は Square Dashboard で管理します。
注文と返金
注文ステータス
No order yet：カードが拒否された場合、または Square の応答が失われ、支払いが見つからなかった場合です。カートだけが存在します。
Payment accepted：Square が、カート合計に一致する COMPLETED の支払いを確認しました。支払いは、Square の支払い ID をトランザクション ID として記録され、備考には支払い ID、カードブランドと下 4 桁、モード（sandbox または live）が表示されます。
Square payment on hold：Square の応答が COMPLETED ではない支払い（例：APPROVED）であった場合、または金額、通貨、参照番号、ロケーションが異なる場合です。Square 支払いの確認が必要ですという備考には、支払い ID、ステータス、金額が表示されます。COMPLETED の支払いは、Square が請求した金額で注文に記録されます。このステータスは、支払い中にカートが変更された場合や、Square の応答が失われて確認できなかった場合にも使用されます（その場合は支払いは記録されません）。発送の前に、Square Dashboard で支払いを確認してください。
Refunded：支払いはモジュールを通じて全額返金されました。
すでに注文があるカートに 2 回目の支払いが届いた場合、注文は変更されません。備考で、その支払いを確認し、重複分を Square Dashboard で返金するよう促されます。
Square ブロック
注文画面には Square ブロックが表示されます。内容は、Square の支払い ID（Square Dashboard の支払いへのリンク付き）、Square のステータス、カードブランドと下 4 桁、Paid / order / refunded の金額、環境とロケーション、Square の領収書へのリンク、sandbox 支払いの Sandbox バッジ、返金履歴、注文の Square notes です。カード番号は保存されません。
返金
Square ブロックに金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Square をクリックします。確認メッセージ Square 経由でこの金額を返金しますか？この操作は取り消せません。 を承認します。全額返金と一部返金に対応しています。注文を編集する権限が必要です。返金は、Square が請求した金額と通貨で行われます。そのため、金額の不一致が発生した場合でも、注文合計ではなく、購入者が実際に支払った金額まで返金できます。返金は、支払いが行われた環境（sandbox または本番）とロケーションに送信されるため、そのモードの Access Token が設定されている必要があります。返金リクエストは冪等で、Square から応答がない場合は 1 回再試行されます。Square が受け付けた返金（ステータス PENDING または COMPLETED）は、Square の返金 ID とともに返金履歴と備考に追加されます。Square が拒否した場合は、ブロックにエラーが表示され、返金は記録されません。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。
本モジュールはクレジットスリップを作成しません。注文画面の PrestaShop の標準の返金ボタンは、Square を通じて返金しません。Square は返金を自社側で完了させます。後で Square が拒否した返金は報告されず、Square Dashboard で行った返金は PrestaShop には表示されません。
ライセンスキー
本モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Square Gateway は Modules > Module Manager > VibeFox Square Gateway > Configure ページの最上部、設定の上にある最初のブロックです。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはキーがマスクされて表示され、ステータス（例：ライセンスの有効期限日と使用中のドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-square の行と、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 のアカウントで解放してください。
有効なキーがない場合、Square はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のフロントエンドは、管理画面にログインしていることを認識しないため、お客様にも支払い方法は非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブに通知が表示されます。既存の注文には影響しません。支払い済みの注文は支払い済みのままで、返金も機能します。
ライセンスの有効期限が切れた後も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面で作業している間に自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
Square がチェックアウトに表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの Application ID、Access Token、Location ID が入力されていることを確認してください。カートの通貨が USD、CAD、AUD、JPY、GBP、EUR のいずれかで、Square ロケーションの通貨と一致しているか確認してください。設定ページには、これらの各問題に対する警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループに対して許可されているか確認してください。
カードフォームが読み込まれない：購入者には カードフォームを読み込めませんでした。ページを再読み込みするか、別の支払い方法を選択してください。 と表示されます。Application ID と Location ID が選択中のモードに属しているか確認してください（sandbox の ID は sandbox- で始まります）。購入者がクリックするのが早すぎた場合は、カードフォームを読み込み中です。しばらく待ってから再度お試しください。 と表示されます。
保存後に支払い方法が消えた：Square ロケーションの通貨がカートの通貨と異なります。ショップの通貨を使用する Square ロケーションの Location ID を入力して、再度保存してください。確認に成功すると、支払い方法が再び表示されます。
Square が選択中のモードの Access Token を拒否した：トークンが別のモードのものか、誤っています。アプリケーションの Credentials ページから再度コピーし、Sandbox Mode を確認してください。
この Access Token の Location ID が見つからない：同じアプリケーションおよび同じモードの Locations ページから Location ID をコピーしてください。
購入者に「支払いプロバイダーから確認を取得できませんでした」と表示された：Square から応答がなく、まだ支払いが見つかっていません。Square Dashboard で、このロケーションの支払いを確認してください（参照 = カート ID）。購入者が再度試した場合、モジュールはまず以前の支払いを探し、再請求する代わりにその支払いで注文を作成します。
購入者に「お支払いは受け付けましたが、注文を自動で完了できませんでした」と表示された：カードは請求されましたが、PrestaShop は注文を作成できませんでした（たとえば、その時点でモジュールが無効になっていた場合）。ログを確認し、注文を手動で作成するか、Square Dashboard で支払いを返金してください。
注文が Square payment on hold になっている：Square ブロックの備考を確認してください（注文ステータスを参照）。Square Dashboard で支払いを確認し、注文を発送するか、支払いを返金してください。
モードに関するメッセージで返金に失敗する：支払いは sandbox または live モードで行われましたが、そのモードの Access Token が設定されていません。Access Token を入力して、再度お試しください。
その他のエラー：Debug log をオンにし、モジュールのページにある Log フィールドを確認してください。
アンインストール
Modules > Module Manager に進み、VibeFox Square Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、ゲートウェイの設定とログファイルが削除されます。オフの場合、すべての設定は後で再インストールするために保持されます。注文に紐づく Square の支払いと返金、および注文ステータス Square payment on hold は常に保持されるため、以前に支払い済みの注文は、再インストール後も返金できます。既存の注文は、支払いの備考、Square の支払い ID、トランザクション ID を保持します。
Square は、それぞれの所有者の商標です。本モジュールは Square と提携しておらず、Square による推奨もされていません。