VibeFox Square for WooCommerce — ヘルプ
要件
WordPress：6.0 以降。
WooCommerce：7.0 以降。インストールされ、有効化されている必要があります。WooCommerce がないとプラグインは有効化できません。
PHP：8.0 以降。
ストアの通貨：Square ロケーションの通貨（USD、CAD、AUD、JPY、GBP、EUR）。その他の通貨では、チェックアウトで決済方法が表示されません。Square が対応しているのは、米国、カナダ、オーストラリア、日本、英国、アイルランド、フランス、スペインの販売者です。
Square アカウント：Square Developer Dashboard にアプリケーションが必要です。そこから、Application ID と Access Token（Credentials ページ）、Location ID（Locations ページ）をコピーします。Sandbox と Production では値が別々です。ウェブフックは不要です。プラグインは Square の応答から直接決済結果を取得します。
VibeFox ライセンスキー：vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ使用できます。
インストール
1. WordPress で Plugins > Add New > Upload Plugin を開き、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_square_gateway フォルダを /wp-content/plugins/ にアップロードすることもできます。
2. Activate をクリックします。
3. 設定を開きます：WooCommerce > Settings > Payments > Square > Manage。または、プラグインのページでプラグイン名の下にある Settings をクリックします。
4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。
5. Sandbox Mode をオンのままにし、サンドボックスの Application ID、Access Token、Location ID を入力します（「設定」を参照）。保存すると、プラグインが Square で認証情報を確認します。
6. Enable/Disable をオンにし、Square のサンドボックス テストガイドに記載されたテストカードで決済を試します。その後 Sandbox Mode のチェックを外し、本番環境の認証情報を入力して、もう一度保存します。
設定
すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Square。サンドボックスモードがオンの間、ページには項目の上に Square Gateway は現在 SANDBOX モードです。実際の請求は行われません。 と表示されます。また、Square が有効なのに選択中のモードの Application ID、Access Token、Location ID が未入力の場合（この場合、チェックアウトで決済方法は表示されません）や、Square がストアの通貨を処理できない場合には警告が表示されます。決済方法の一覧では、サンドボックスモードがオンの間、Square に Test mode バッジが表示されます。
保存すると、プラグインは選択中のモードの認証情報を Square で確認します。Square が Access Token を拒否した場合、そのトークンに対するロケーション ID が見つからない場合、認証情報を確認できなかった場合、またはロケーションの通貨がストアの通貨と異なる場合は、エラーが表示されます。Square はロケーションの通貨でのみ請求できます。プラグインは確認済みロケーションの通貨を保存し、それ以外の通貨では、チェックアウトで決済方法を非表示にします。設定ページにも警告が表示され続けます。また、サンドボックスの Application ID を本番モードで使用した場合、またはその逆の場合にも警告します。
General
Enable/Disable：Enable Square Payment Gateway で、決済方法のオン／オフを切り替えます。デフォルト：off。
Title：チェックアウト時に購入者に表示される決済方法のタイトルです。デフォルト：Credit / debit card。
Description：チェックアウト時に購入者に表示される決済方法の説明です。デフォルト：Pay securely with your credit or debit card via Square。
Square account
Square Developer Dashboard を開き、アプリケーションを選択して、Credentials ページから Application ID と Access token（Sandbox と Production では値が別々）を、Locations ページから Location ID をコピーします。ロケーションの通貨は、ストアの通貨と一致している必要があります。このページには、選択中のモードの認証情報フィールドだけが表示されます。Sandbox Mode がオンの間はサンドボックスのフィールド、オフの間は本番のフィールドが表示されます。
Sandbox Mode：Enable sandbox (test) mode。決済は Square のサンドボックスに送信され、実際の請求は行われません。Square のテストカードを使用してください。デフォルト：on。
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。
Advanced
Debug log：Log API requests and responses。エラーは常に記録されます。オンにすると、すべてのリクエストも記録されます（カードデータやキーは含まれません）。ログは WooCommerce > Status > Logs にあり、ソースは wcp_square_gateway です。デフォルト：off。
Delete data on uninstall：Remove all plugin data when the plugin is deleted。プラグインを削除すると、ゲートウェイの設定とログファイルが削除されます。注文の支払いデータは保持されます。デフォルト：off。
チェックアウト
購入者は決済方法（デフォルトは Credit / debit card）を選び、説明の下に表示される Square カードフォームにカード情報を入力します。サンドボックスモードでは、チェックアウトにサンドボックスの通知が表示されます。購入者が Place order をクリックすると、カードはブラウザ内で購入者の本人確認（3-D Secure / SCA）を伴ってトークン化されます。金額、通貨、請求先の連絡先は Square に渡され、購入者の銀行が確認を求めることがあります。貴店のサーバーが受け取るのは 1 回限りのトークンだけです。
その後、プラグインは Square Payments API を通じて、注文の通貨で注文合計をトークンで請求します。参照として注文 ID、注文番号と貴店のサイト名を含む Order # の備考、および請求先のメールアドレスを送信します。支払いは即時に売上として確定します。注文が支払い済みとしてマークされるのは、Square が確認した後だけです。Square の応答には、注文合計、通貨、注文 ID、ロケーションが完全に一致する COMPLETED の支払いが表示されている必要があります。その後、購入者は注文受付ページに進みます。支払いが COMPLETED でない場合や値が一致しない場合、注文は備考付きで保留になりますが、購入者は注文受付ページに進みます。
注文ごとに同時に実行される支払い試行は 1 回だけです。購入者が 2 回クリックしたり、2 つのタブで支払いを行ったりした場合、2 回目の試行では This order is already being paid. Please wait a moment and check your e-mail before trying again.（この注文は既に支払い処理中です。少し待ってからメールを確認し、再度お試しください。）と表示されます。リクエストは冪等です。同じ注文、トークン、金額の組み合わせでは、2 つ目の支払いが作成されることはありません。
Square から応答がない場合（ネットワークの問題、タイムアウト、サーバーエラー）、同じ冪等性キーでリクエストが 1 回再試行されます。それでも応答がない場合、購入者には We could not get a confirmation from the payment provider. Please wait a minute and try again — if your card was already charged, the payment will be recognised and you will not be charged twice.（決済プロバイダーから確認を得られませんでした。1 分ほど待ってから再度お試しください。カードに既に請求されていた場合は、決済が認識され、二重請求にはなりません。）と表示されます。注文備考には、Square Dashboard の確認を促す内容が記載されます。次回の試行では、プラグインがまず Square でこの注文の以前の支払いを確認し、その支払いで注文を完了させます。カードを再度請求することはありません。
銀行がカードを拒否した場合、購入者には Square のエラーコードに応じた短いメッセージが表示されます。例：Your card was declined. Please use another card or payment method.、The card security code (CVV) is incorrect. Please check it and try again.、Your bank requires additional verification (3-D Secure). Please enter your card again and complete the verification.。技術的な理由は注文備考とログに記録されます。購入者は別のカードで再試行できます。後から Pay for order ページで再試行することもできます。
この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで利用できます。WooCommerce High-Performance Order Storage（HPOS）に対応しています。
本プラグインは、即時に売上を確定するカード決済のみに対応しています。保存済みカードや顧客プロフィール、WooCommerce Subscriptions や予約注文、Apple Pay、Google Pay、Cash App Pay、Afterpay、ACH、Square ギフトカード、オーソリのみの決済、Square ウェブフック、Square との商品や在庫の同期には対応していません。紛争（チャージバック）は Square Dashboard で管理します。
注文と返金
注文ステータス
Pending payment：注文は作成されていますが、まだ支払われていません。たとえば、カードが拒否された後や、Square からの応答が届かなかった後です。
Processing：Square が注文合計の COMPLETED の支払いを確認しました。これは支払い後の WooCommerce の標準ステータスです（ダウンロード可能な仮想商品のみの注文は完了になります）。注文備考には、Square の支払い ID、カードブランドと末尾 4 桁、モード（サンドボックスまたは本番）が表示されます。取引 ID は Square の支払い ID であり、注文画面では Square Dashboard の該当する支払いにリンクされます。
On hold：Square が、COMPLETED ではない支払い、または金額、通貨、参照番号、ロケーションが異なる支払いで応答しました。Square payment needs review という備考には、支払い ID、ステータス、金額が表示されます。発送の前に、Square Dashboard で売上確定、金額、通貨を確認してください。
プラグインは、Square の支払い ID、カードブランドと末尾 4 桁、環境、ロケーションを注文に保存します。カード番号は保存されません。
返金
注文を開き、Refund をクリックして金額を入力し、Refund via Credit / debit card をクリックします（ボタンには、設定した Title が表示されます）。全額返金と一部返金に対応しています。返金は、支払いが行われた環境（サンドボックスまたは本番）とロケーションに送信されるため、そのモードの Access Token を設定しておく必要があります。返金リクエストは冪等で、Square から応答がない場合は 1 回再試行されます。Square が受け付けた返金（ステータス PENDING または COMPLETED）は、Square の返金 ID とともに注文備考に追加されます。Square が返金を拒否した場合、WooCommerce にエラーが表示され、返金は記録されません。
Square は返金を自社側で完了させます。後から Square が拒否した返金は WooCommerce に通知されません。また、Square Dashboard で行った返金は WooCommerce には表示されません。
ライセンスキー
プラグインは、vibefox.net で購入した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > Square の上部にあります。キーを License key に貼り付けて、Activate をクリックします。ブロックには、ステータス（ライセンスの有効期限など）と、ご利用のドメインが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除できます。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。
1 つのキーは 1 つのドメインでのみ使用できます。サイトからキーを削除しても、そのドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、Square はチェックアウトで購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one.（この決済方法はご利用いただけません。別の方法をお選びください。）と表示されます。ログインしている店舗管理者には、(unlicensed — visible to admins only) と表示付きで決済方法が表示されます。そのため、キーを購入する前にプラグインを設定してテストできます。プラグインのページと WooCommerce のページには、リマインダーが表示されます。既存の注文には影響しません。支払い済みの注文は支払い済みのままで、返金も使用できます。
ライセンスの期限が切れても、プラグインは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、バックグラウンドで自動的に再確認されます。
トラブルシューティング
チェックアウトに Square が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの Application ID、Access Token、Location ID が入力されていることを確認してください。ストアの通貨（または Pay for order ページの注文通貨）が USD、CAD、AUD、JPY、GBP、EUR のいずれかで、Square ロケーションの通貨と一致していることを確認してください。設定ページには、これらの問題ごとに警告が表示されます。
カードフォームが読み込まれない：購入者には The card form could not be loaded. Please reload the page or choose another payment method.（カードフォームを読み込めませんでした。ページを再読み込みするか、別の決済方法を選んでください。）と表示されます。Application ID と Location ID が選択中のモードに対応しているか確認してください（サンドボックスの ID は sandbox- で始まります）。購入者が早すぎるタイミングでクリックした場合は、The card form is still loading. Please wait a moment and try again.（カードフォームを読み込んでいます。少し待ってから再度お試しください。）と表示されます。
カードは問題ないのに決済が拒否される：ロケーションの通貨は、ストアの通貨と一致している必要があります。設定を保存して、認証情報の確認結果を確認してください。確認に成功すると、他の通貨では決済方法が非表示になります。
Square が選択中のモードの Access Token を拒否した：そのトークンは別のモードのものか、誤っています。アプリケーションの Credentials ページから再度コピーし、Sandbox Mode の設定を確認してください。
この Access Token に対応する Location ID が見つからない：同じアプリケーションおよび同じモードの Locations ページから Location ID をコピーしてください。
購入者に「We could not get a confirmation from the payment provider」と表示された：Square が応答しませんでした。注文備考を確認し、Square Dashboard でこのロケーションの支払い（参照 = 注文 ID）を確認してください。購入者が再試行すると、プラグインはまず以前の支払いを確認し、その支払いで注文を完了させます。再度請求することはありません。
注文が On hold になっている：Square payment needs review の備考を確認してください。支払いが COMPLETED ではなかったか、金額、通貨、ロケーションが注文と異なっていました。Square Dashboard で確認し、そのうえで注文を処理するか、支払いを返金してください。
モードに関するメッセージが表示されて返金に失敗する：支払いはサンドボックスモードまたは本番モードで行われ、そのモードの Access Token が設定されていません。Access Token を入力して、もう一度お試しください。
その他のエラー：Debug log をオンにして、WooCommerce > Status > Logs（ソースは wcp_square_gateway）を確認してください。
ライセンスブロックにエラーが表示される：ブロックのメッセージに従ってください。たとえば、そのキーが別のドメインで既に使用されている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックしてください。サイトのアドレスが変わった場合は、Check now をクリックして新しいドメインでキーを有効化してください。ライセンスサーバーに接続できない場合、プラグインは最後に確認できたステータスで動作を続けます。
アンインストール
プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページでプラグインを無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイの設定とログファイルは、Delete data on uninstall がオンの場合にのみ削除されます。それ以外の場合は、後で再インストールする際に使用できるように残ります。既存の注文には、支払いの備考、Square の支払い ID、取引 ID が残ります。
Square は、各所有者の商標です。本プラグインは Square と提携しておらず、Square による推奨も受けていません。