VibeFox Square for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。
PHP: 8.0 以降。
通貨: 注文の通貨は Square ロケーションの通貨と同じである必要があります: USD、CAD、AUD、JPY、GBP、EUR。それ以外の通貨では、チェックアウトで支払い方法が表示されません。JPY は整数の円単位で請求されます。
Square アカウント: Square Developer Dashboard でアプリケーションを作成する必要があります。そこから Application ID と Access Token（Credentials ページ）、Location ID（Locations ページ）をコピーします。Sandbox と Production の値は別々です。Webhook は不要です。拡張機能は Square の応答から直接決済結果を取得します。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
このダウンロードは、両方の OpenCart バージョン用パッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。中には README.txt、OpenCart 3 用パッケージ wcp_square_gateway-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_square_gateway.ocmod.zip が含まれています。ご利用の OpenCart のバージョンに合ったパッケージだけをインストールしてください。ライセンスキーは両バージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer を開き、Upload をクリックして、ファイル wcp_square_gateway-oc3-(version).ocmod.zip を選択します。この拡張機能には OCMOD による変更がないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダーの内容をストアのルートフォルダーにコピーすることもできます。
2. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox Square Gateway を探して、Install（緑色の + ボタン）をクリックします。管理者ユーザーに、決済拡張機能の一覧を変更する権限が必要です。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーを参照）。
4. Sandbox Mode をオンのままにして、サンドボックスの Application ID、Access Token、Location ID を入力します（設定を参照）。Save をクリックすると、拡張機能が Square で認証情報を確認します。
5. Enable/Disable をオンにして保存し、Square のサンドボックステストガイドにあるテストカードで決済を試します。その後 Sandbox Mode をオフにし、本番の認証情報を入力して、もう一度保存します。
OpenCart 4
1. 管理画面で Extensions > Installer を開き、Upload をクリックして、ファイル wcp_square_gateway.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 はファイル名から拡張機能のコードを取得するため、名前を変更したパッケージは動作しません。
2. インストール済み拡張機能の一覧に、同じページでパッケージが表示されます。その横にある Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox Square Gateway を探して、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと Square の認証情報は、OpenCart 3 の手順 3〜5 と同じように入力します。設定ページとそのフィールドは両バージョンで同じです。
新規インストール時は、支払い方法がオフ、サンドボックスモードがオンの状態で始まります。
設定
すべての設定は拡張機能のページにあります: Extensions > Extensions > Payments > VibeFox Square Gateway > Edit。セクションは左側に一覧表示され、一覧の下にある Save ボタンでページ全体を保存します。サンドボックスモードがオンの間、設定の上には Square Gateway は現在 SANDBOX モードです。実際の請求は行われません。 と表示されます。また、Square が有効なのに選択中のモードの Application ID、Access Token、Location ID が未入力の場合（この場合、チェックアウトで支払い方法が非表示になります）、Square がストアの既定の通貨を処理できない場合、Square ロケーションの通貨がストアの通貨と異なる場合にも警告します。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。
保存時、Title は空にできません（最大 128 文字）。Sort Order は整数である必要があります（負の値も使用できます）。Total は 0 以上の数値である必要があります。また、ジオゾーンと注文ステータスは存在している必要があります。満たさない場合、何も保存されません。その後、拡張機能は選択中のモードの認証情報を Square で確認します。設定はいずれの場合も保存され、警告は設定の上の赤いブロックに表示されます。Square が Access Token を拒否した、この Token で Location ID が見つからない、認証情報を確認できなかった、またはロケーションの通貨がストアの通貨と異なる、といった場合です。Square はロケーションの通貨でのみ請求できます。拡張機能は確認済みロケーションの通貨を記憶し、ほかの通貨の注文では支払い方法を非表示にします。また、サンドボックスの Application ID を本番モードで使っている場合、またはその逆の場合も警告します。
Square
Enable/Disable: Enable Square Payment Gateway で支払い方法のオン・オフを切り替えます。既定値: オフ。
Title: 購入者がチェックアウトで見る支払い方法の名前です。注文に保存される支払い方法名にもなります。既定値: Credit / debit card。必須。
Description: 購入者が Confirm Order の段階で、カードフォームの上に見るテキストです。既定値: Pay securely with your credit or debit card via Square.
Sort Order: チェックアウトの支払い方法の中で、カード決済を表示する位置です。空欄のままにするか、整数を入力します（負の値も使用できます）。
Geo Zone: 選択したジオゾーン内の支払い先住所に対してのみ、カードフォームを提供します。既定値: All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。
Total: 支払い方法が提供されるために注文が達している必要がある、ストアの既定の通貨でのチェックアウト合計額です。空欄にすると、どの金額でも提供されます。
Square アカウント
Square Developer Dashboard を開き（このセクションからリンクされています）、アプリケーションを選択して、Credentials ページから Application ID と Access token（Sandbox と Production で値は別々です）をコピーし、Locations ページから Location ID をコピーします。ロケーションの通貨はストアの通貨と一致している必要があります。このページには、選択中のモードの認証情報欄のみが表示されます。Sandbox Mode がオンの間はサンドボックス欄、オフの間は本番欄です。どちらのセットも保存されたままになります。
Sandbox Mode: 支払いは Square のサンドボックスに送られ、実際の金額は請求されません。Square のテストカードを使用してください。既定値: オン。注文の返金は、常にその注文が支払われた環境とロケーションを使用します。
Sandbox Application ID: Square サンドボックスの Application ID です（sandbox-sq0idb- で始まります）。
Sandbox Access Token: Square サンドボックスの Access Token です。
Sandbox Location ID: Square サンドボックスの Location ID です。
Live Application ID: Square 本番環境の Application ID です（sq0idp- で始まります）。
Live Access Token: Square 本番環境の Access Token です。
Live Location ID: Square 本番環境の Location ID です。
保存済みの Access Token は再び表示されません。欄は空のままで、保存済み — 変更しない場合は空欄のままにしてください。 と表示されます。変更する場合にのみ新しい値を入力してください。保存済みの Access Token を削除するには、欄の下にある Clear the saved value on save にチェックを入れ、Save をクリックします。
注文
OpenCart は、Confirm Order の段階でステータスのない注文（未完了の注文）を作成します。注文がステータスを得るのは、Square が支払いに応答した後だけです。以下の各欄には、OpenCart の注文ステータスが一覧表示されます。
Order Status After Payment: Square が注文の金額と通貨とちょうど一致する支払いを完了しました。既定値: Processing。
On Hold (Review) Status: 支払いにはご自身による確認が必要です（注文ステータスを参照）。既定値: Pending。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。
Refunded Status: 注文ページから支払い全額が返金された後に設定されます。既定値: Refunded。
詳細設定
Debug log: エラーと警告は常に記録されます。オンにすると、カードデータやキーを除くすべてのリクエストとレスポンスも、OpenCart のログフォルダー（storage/logs）内の wc_sqg_debug.log.php に記録されます。このファイルは Web から開くことはできず、5 MB に達すると wc_sqg_debug.old.log.php に移動されます。既定値: オフ。
Log: ログのサイズと最新のエントリーを表示します。Clear log をクリックすると、ログが空になります。
Delete data on uninstall: オンにすると、拡張機能をアンインストールしたときにゲートウェイの設定とログファイルが削除されます。注文の Square による支払いと返金は、常に保持されます。既定値: オフ。
インポート / エクスポート
Export: Download JSON で、設定を JSON ファイルとして保存します。Access Token はエクスポートされません。
Import: 以前エクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みの Access Token は保持されます。
チェックアウト
Payment Method の段階で、購入者は支払い方法を選択します（既定では Credit / debit card）。Confirm Order の段階では、購入者に Credit / debit card (Square)、設定した説明文、サンドボックスモードがオンの間は サンドボックスモード — 実際の請求は行われません。、そして Square のカードフォームが表示されます。OpenCart はこの段階で注文を作成しますが、まだステータスはありません。購入者が Confirm Order をクリックすると、カードはブラウザー内で購入者認証（3-D Secure / SCA）とともにトークン化されます。注文金額、通貨、支払い先住所が Square に渡され、購入者の銀行が確認を求める場合があります。貴店が受け取るのは、1 回限りのトークンだけです。OpenCart 4 では、購入者は支払い方法ブロックの Choose ボタンを使い、Payment method options ウィンドウで支払い方法を選択します。その後、Square のカードフォームは、チェックアウトページ下部の確認ブロック内、Confirm Order の上に表示されます。
次に拡張機能は、注文の通貨で注文金額について、Square Payments API を通じてトークンに請求します。参照として注文番号、注文番号とストア名を含む Order # のメモ、購入者のメールアドレスが付与されます。支払いは直ちにキャプチャされます。注文が支払い済みとしてマークされるのは、Square が確認した後だけです。Square の応答には、注文の合計額、通貨、注文番号、ロケーションとちょうど一致する COMPLETED の支払いが示されている必要があります。その後、注文は OpenCart の標準的な方法で Order Status After Payment を取得し、通常の注文メールと在庫の更新が行われます。購入者には OpenCart の注文完了ページが表示され、カード決済を受け付けました。 と、Square のレシートへのリンク View the receipt が表示されます。支払いが COMPLETED でない場合、または値が一致しない場合、注文は On Hold (Review) Status を取得し、ページには カード決済を受け付けましたが、確認中です。確認が完了次第、注文を更新します。 と表示されます。
カートごとに同時に実行される決済の試行は 1 回だけです。購入者が 2 回クリックした場合、または 2 つのタブで支払いを試みた場合、2 回目の試行には この注文はすでに支払い処理中です。しばらく待ってから、メールを確認してから再度お試しください。 と表示されます。リクエストは冪等（べきとう）であり、Confirm Order の段階が表示されるたびに OpenCart 3 は新しい注文を作成するため、拡張機能はカートを追跡します。支払い済みのカートに再び請求されることはなく、購入者は直接成功ページに進みます。
Square から応答がない場合（ネットワークの問題、タイムアウト、サーバーエラー）、同じ冪等キーでリクエストが 1 回再試行されます。それでも応答がなければ、拡張機能は直ちに Square でこの注文の支払いを探します。見つかった場合、その支払いに基づいて注文がステータスを取得します。支払いが見つからない場合、購入者は Confirm Order の段階に留まり、決済プロバイダーから確認を得られませんでした。1 分ほど待ってから再度お試しください。カードがすでに請求されている場合、支払いは認識され、二重に請求されることはありません。 と表示されます。同じカートの次の試行では、まず以前の支払いを再度探します。Square がこの検索にも応答しない場合、注文は支払いなしで On Hold (Review) Status を取得し、カードが請求された可能性があるというメモが付きます。成功ページには Square からカード決済の確認を得られませんでした。再度お支払いになる前に、メールとカードの明細をご確認いただくか、お問い合わせください。 と表示されます。
銀行がカードを拒否した場合、注文はステータスのないままになり、購入者は Confirm Order の段階に留まって、Square のエラーコードに応じた短いメッセージが表示されます。例: カードが拒否されました。別のカードまたは支払い方法をご利用ください。、カードのセキュリティコード（CVV）が正しくありません。ご確認のうえ、再度お試しください。、または お使いの銀行で追加の認証（3-D Secure）が必要です。カードを再度入力し、認証を完了してください。 カートは保持され、購入者は別のカードで再試行できます。技術的な理由はログに記録されます。
OpenCart 4 では、チェックアウトの注文を 1 つ保持して更新するため、カードが拒否された後、購入者は同じ注文を支払い直します。Square から応答が得られなかった支払いの後は、その注文の次の試行がまず以前の支払いを探します。チェックアウトの注文にすでにステータスがある（支払い済みになっている、または店舗によって閉じられている）場合で、カートに新しい商品が含まれているときは、購入者はチェックアウトに戻され、新しいカートは新しい注文で支払われます。
この拡張機能はカード決済のみを受け付け、即時にキャプチャします。保存済みカード、顧客プロファイル、サブスクリプション、Apple Pay、Google Pay、Cash App Pay、Afterpay、ACH、Square ギフトカードには対応していません。承認のみの支払い、Square の Webhook、Square との商品や在庫の同期も行いません。チャージバックは Square Dashboard で管理します。
注文と返金
注文ステータス
ステータスなし（未完了の注文）: 購入者がまだ支払っていない、カードが拒否された、または Square の応答が失われ、支払いが見つからなかった場合です。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。
Order Status After Payment（既定値 Processing）: Square が注文の合計額について COMPLETED の支払いを確認しました。メモには、Square の支払い ID、カードブランドと下 4 桁、モード（サンドボックスまたは本番）が表示されます。
On Hold (Review) Status（既定値 Pending）: Square が COMPLETED ではない支払い（例: APPROVED または PENDING）で応答したか、金額、通貨、参照、ロケーションが異なる応答をしました。Square の支払いの確認が必要です というメモには、支払い ID、ステータス、金額が表示されます。このステータスは、支払い中に注文が変更された場合や、Square の応答が失われて確認できなかった場合にも使用されます（後者の場合、支払いは記録されず、メモでは注文番号を参照として Square Dashboard でロケーションの支払いを確認するよう求められます）。発送前に Square Dashboard で支払いを確認してください。
Refunded Status（既定値 Refunded）: 支払いが拡張機能を通じて全額返金されました。
すでに支払い済みの注文があるカートに対して 2 回目の支払いが行われた場合、支払い済みの注文は変更されません。メモで確認し、重複分を Square Dashboard で返金するよう求められます。
メモは、購入者には表示されない注文の History の項目です。
VibeFox Square Gateway タブ
Sales > Orders で、Square で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox Square Gateway タブには、Square の Payment ID（Square Dashboard の支払いにリンク）が表示されます。サンドボックスの支払いには Sandbox ラベルが付きます。また、Square の Status、Card ブランドと下 4 桁、Paid / order / refunded の金額、Environment / location、Square receipt のリンク、返金フォーム、返金履歴、注文の Square notes も表示されます。カード番号は保存されません。このタブは、拡張機能へのアクセス権があるユーザーに表示されます。
返金
VibeFox Square Gateway タブで Amount を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて Reason (optional) を入力し、Refund via Square をクリックします。この金額を Square 経由で返金しますか？この操作は取り消せません。 という確認に応じてください。全額返金と一部返金に対応しています。拡張機能を変更する権限が必要です（System > Users > User Groups で設定します）。返金は Square が請求した金額と通貨で行われます。そのため、金額に差異がある場合は、注文合計ではなく購入者が実際に支払った額まで返金できます。返金は支払いが行われた環境（サンドボックスまたは本番）とロケーションに送られるため、そのモードの Access Token が設定されている必要があります。返金のリクエストは冪等であり、Square が応答しなかった場合は 1 回再試行されます。Square が受け付けた返金（ステータス PENDING または COMPLETED）は、Square の返金 ID とともに返金履歴とメモに追加されます。Square が拒否した場合、タブにエラーが表示され、返金は記録されません。全額返金では、注文は購入者に通知されず、商品も在庫に戻されずに Refunded Status に設定されます。手動でステータスを変更した場合と同じです。一部返金ではステータスは変わりません。
Sales > Returns での商品返品では、Square を通じて返金は行われません。Square は返金を自身の側で完了します。後で Square が拒否した返金は報告されず、Square Dashboard で行われた返金は OpenCart には表示されません。
ライセンスキー
この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox Square Gateway のライセンスブロックは、Extensions > Extensions > Payments > VibeFox Square Gateway > Edit の最初のブロックで、設定の上に表示されます。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例: ライセンスの有効期限日とドメイン）、そして次のボタンが表示されます。ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key。その下には、Product: opencart-payment-square の行と、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 のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで購入者に Square は表示されません。それでも支払いが開始された場合、購入者には 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 ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
Square がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの Application ID、Access Token、Location ID が入力されていることを確認してください。購入者の通貨が USD、CAD、AUD、JPY、GBP、EUR のいずれかであり、Square ロケーションの通貨と一致していることも確認してください。設定ページには、これらの問題ごとに警告が表示されます。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。
カードフォームが読み込まれない: 購入者には カードフォームを読み込めませんでした。ページを再読み込みするか、別の支払い方法をお選びください。 と表示されます。Application ID と Location ID が選択中のモードに属していることを確認してください（サンドボックスの ID は sandbox- で始まります）。購入者が早すぎるクリックをすると、カードフォームを読み込み中です。しばらく待ってから再度お試しください。 と表示されます。
保存後に支払い方法が消えた: Square ロケーションの通貨が注文の通貨と異なります。ストアの通貨の Square ロケーションの Location ID を入力し、もう一度保存してください。確認が成功すると、支払い方法が再び表示されます。
Square が選択中のモードの Access Token を拒否した: そのトークンは別のモードのものか、誤っています。アプリケーションの Credentials ページから再度コピーし、Sandbox Mode を確認してください。
この Access Token に対する Location ID が見つからない: 同じアプリケーションと同じモードの Locations ページから Location ID をコピーしてください。
購入者に「決済プロバイダーから確認を得られませんでした」と表示された: Square が応答せず、支払いはまだ見つかっていません。Square Dashboard でこのロケーションの支払い（参照 = 注文番号）を確認してください。購入者が再試行すると、拡張機能はまず以前の支払いを探し、再度請求する代わりにそれを使用します。
購入者に「お支払いは受け付けられましたが、注文を自動的に完了できませんでした」と表示された: カードは請求されましたが、OpenCart は注文ステータスを設定できませんでした。ログを確認してから、注文を手動で完了するか、Square Dashboard で支払いを返金してください。
購入者に「この支払い方法は注文に使用できません」と表示された: チェックアウトが注文と一致しなくなった、支払い方法がその間にオフにされた、または注文の通貨で請求できないことを意味します。購入者はチェックアウトを再読み込みするか、別の支払い方法を選択します。
支払い後に注文が確認ステータスになっている: VibeFox Square Gateway タブのメモを確認してください（注文ステータスを参照）。Square Dashboard で支払いを確認してから、注文を完了するか、支払いを返金してください。
タブに返金フォームがない: タブに理由が表示されます。この注文の代金を受け取った Square の支払いがない、Square の支払い ID が記録されていない（その場合、タブには Square Dashboard で検索すべきロケーションと注文番号が表示されます）、支払いが全額返金済みである、またはユーザーグループに拡張機能を変更する権限がない、のいずれかです。
モードに関するメッセージで返金が失敗する: 支払いはサンドボックスまたは本番モードで行われており、そのモードの Access Token が設定されていません。入力してから再度お試しください。
その他のエラー: Debug log をオンにして、拡張機能ページの Log 欄を確認してください。
アンインストール
Extensions > Extensions に移動し、種類として Payments を選択して、VibeFox Square Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は拡張機能自身の設定を常に削除します。具体的には、Enable/Disable、Sort Order、Geo Zone、Total、そして Orders セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます。Delete data on uninstall がオンの場合、残りのゲートウェイ設定（タイトル、説明、サンドボックスモード、認証情報、ログ）とログファイルも削除されます。オフの場合、後で再インストールするために保持されます。注文の Square による支払いと返金は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は支払いメモを保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧にある VibeFox Square Gateway の横の Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱のボタン）をクリックしてください。
Square は、それぞれの所有者の商標です。この拡張機能は Square と提携しておらず、Square による推奨も受けていません。