Square Terminalゲートウェイ
Square Terminalゲートウェイを使用すると、WCPOSから直接Square TerminalハードウェアでWooCommerce注文の支払いを受け付けられます。支払いはWooCommerceから要求され、ペアリング済みのSquare Terminalデバイスで完了し、その結果が注文に書き戻されます。
機能
ハードウェア統合
ペアリング済みのSquare Terminalデバイスに支払いを送信し、対面カード決済を受け付けます
ワンクリック接続
Squareで直接認証します。アクセストークンを作成したり貼り付けたりする必要はありません
確実な完了処理
支払いはポーリングとバックグラウンドの照合処理によって確認され、webhookを使えばさらに早くなります
安全な取引
Squareハードウェア上で処理される、PCI準拠のカード対面決済
Sandboxと本番環境
ライブ決済へ切り替える前にSquare Sandboxで検証します
仕組み
ブラウザーSDK型のゲートウェイとは異なり、Square TerminalはSquareのサーバー側Terminal APIを使用します。支払いを開始すると、WooCommerceが注文用のTerminal Checkoutを作成し、Squareがそれをペアリング済みデバイスへプッシュします。顧客は端末で支払い、その結果が注文に書き戻されます。
支払いが確認される仕組み。 支払いの進行中、POS は Square をポーリングし、ポーリングが取りこぼしたもの（たとえばブラウザーのタブが閉じられた場合）はバックグラウンドの照合処理が調整します。Square の webhook は待ち時間を短縮する任意の追加機能であり、必須ではありません。webhook のないサイトでも支払いが失われることはありません。
Square Terminalデバイスはオンラインで、プラグインと同じSquareアカウントおよびロケーションにサインインしている必要があります。
セットアップ
Square Terminal for WooCommerceをインストール
WP Admin > POS > Settings > Extensionsからインストールするか、GitHubリリースページから最新のプラグインzipアセット（GitHubのソースコードzipやtarballではありません）をダウンロードし、Plugins > Add New > Upload Pluginからアップロードします。
Squareに接続
WP Admin > WooCommerce > Settings > Paymentsに移動し、Square Terminalを開きます- Square accountセクションで環境を選択します（テストには
Sandbox、ライブ決済にはProduction） - Connect to Squareをクリックし、Squareに表示される権限を承認します
- Location IDを選択します — Terminalが決済を受け付けるSquareロケーションです
環境は接続する前に選択してください。1つの接続は1つの環境のみを対象とし、Sandboxの接続で本番環境の支払いを承認することはできません。
環境とLocation IDは、そのプラグインの設定から自動的に入力されます。読み取られるのはこの2つの値だけです。プラグイン間で認証情報が共有されることはなく、ここで接続するかアクセストークンを指定する必要があります。
Advanced settingsを開き、接続する代わりに選択した環境のアクセストークンを貼り付けてください。それ以外の動作は同じです。
Square Terminalをペアリング
Terminalセクションで：
- Create Device Codeをクリックすると、ペアリングコードが表示されます
- Square Terminalでデバイスコードのサインイン画面を開き、コードを入力します。Terminal が現在 Square POS や他の連携にサインインしている場合は、先にサインアウトしてください。他で使用されている間はデバイスコード画面に到達できません。
- Check for readersをクリックし、Paired with this pluginに表示されることを確認します
ペアリング前に一覧が空であるのは正常であり、不具合ではありません。Squareのデバイス APIは、Terminal API用にセットアップされたTerminalのみを報告します。Square POSを実行しているTerminalは、デバイスコードを入力するまでまったく表示されません。
WCPOSで有効化
WP Admin > POS > Settings > Checkoutに移動します- Square Terminalゲートウェイを見つけ、POSで有効化します
- 設定を保存します
WooCommerce設定画面のEnable/Disableチェックボックスは、オンラインストアのチェックアウトのみを制御します。WCPOSは、このチェックボックスの状態にかかわらず、設定が完了していればこのゲートウェイを自動的に使用します。
Terminalのペアリング
キャッシャーが選択できるようにするには、Square Terminalをこのプラグインとペアリングする必要があります。ペアリングによってTerminal APIのデバイスコードが作成され、プラグインがデバイスを指定できる唯一の手段となります。
設定画面のTerminalセクションで：
- Create Device Code — Terminalに入力するコードを生成します。短時間しか有効ではないため、期限が切れた場合は新しいものを生成してください。
- Check for readers — Squareが認識しているものを2つのグループに分けて一覧表示します：
- Paired with this plugin — チェックアウトで選択できます
- Other devices Square can see at this location — 別のアプリケーションでセットアップされているため、このプラグインとペアリングするまでここでは選択できません
- Validate Settings — 認証情報とロケーションをSquareに対して確認します
デバイスコードは、それを作成したアプリケーションに属します。そのため、別のTerminal API連携でセットアップされたTerminalはOther devices Square can seeに表示されますが、ここでは選択できません。Square POSを実行しているTerminalはまったく表示されません。
いずれの場合も対処法は同じです。Terminalを現在ペアリングされている対象からサインアウトさせ、ここで新しくCreate Device Codeを実行してコードを入力してください。
Webhook
Webhookは任意です。支払いが確認されるまでの時間を短縮します。ポーリングとバックグラウンドの照合処理がいずれにせよすべての支払いを確認するため、webhookのサブスクリプションがないサイトでも正しく動作します。確定までが少し遅くなるだけです。
Webhookのサブスクリプションは Square のアプリケーションに属しており、追加するには Square Developer Dashboard でそのアプリケーションにアクセスできる必要があります。Connect to Squareで接続した場合、承認しているのはご自身のアプリケーションではなくWCPOSのアプリケーションであるため、サブスクリプションを追加するダッシュボードも、コピーする署名キーもありません。
支払いはポーリングと照合処理によって通常どおり確認されます。以下の手順は、Advanced settingsで独自のアクセストークンを使ってプラグインをセットアップした場合にのみ該当します。
独自のSquareアプリケーションを使ってwebhookを追加するには：
- 設定画面のTerminal → WebhooksでCopyをクリックし、webhook URLをコピーします
- Square Developer Dashboardでアプリケーションを開き、Webhooksに移動します
- **
terminal.checkout.updated**イベントのサブスクリプションを追加し、通知URLとしてそのURLを貼り付けます - SquareのWebhook Signature KeyをプラグインのAdvanced settingsにコピーします
その後、Webhooksの行に、署名が検証されたwebhookが到着したかどうかと、その時刻が表示されます。
Squareは、渡された通知URLに対して各webhookに署名します。Square側のURLがプラグイン側と1文字でも異なると、すべての配信で検証に失敗します。手入力ではなくCopyボタンを使用してください。
SquareのWebhook Subscriptions APIは、個々の販売者ではなくアプリケーションを対象としており、販売者のアクセストークンでは呼び出せません。そのため、プラグインが代わりにサブスクリプションを作成することはできません。
Webhookの検証が通らなくなった場合
現在の設定のもとで検証済みのwebhookがまだ到着していない場合、Webhooksの行にはNot verified yetと表示されます。すでに支払いを実行している場合は、次の順に確認してください。
- Advanced settingsのWebhook Signature KeyがSquare側のものと一致していること
- Square側の通知URLが、プラグインに表示されているURLと完全に一致していること
terminal.checkout.updatedイベントが購読されていること- サイトがHTTPSで公開アクセス可能であること — Square Dashboardで配信試行を確認してください
環境、webhook URL、署名キーを変更すると、次のwebhookが到着するまでこの行はリセットされます。これは意図的な動作です。古い設定のもとで検証された配信は、新しい設定について何も保証しないためです。
設定リファレンス
設定画面は、セットアップの流れに沿って並んでいます。
| セクション | 内容 |
|---|---|
| Square account | 環境、Connect to Square、Location ID |
| Terminal | ペアリングの操作、リーダー一覧、webhookのステータス |
| Checkout behaviour | レシート画面のスキップ、署名の取得、デバッグログ |
| Advanced settings | アクセストークン、webhook署名キー、webhook URLの上書き |
Advanced settingsはデフォルトで折りたたまれています。ここには手動のアクセストークン（接続を使用しない場合にのみ必要）と、webhook署名キーがあります。Webhook URL overrideは、プロキシやカスタムドメインの背後にあるなど、公開URLがプラグインの導出したものと異なる場合を除いて、空のままにしてください。
使用方法
支払いの処理
- アイテムを追加: POSでカートに商品を追加します
- ゲートウェイを選択: 支払い方法として「Square Terminal」を選択します
- デバイスを選択: Terminal Deviceの一覧からペアリング済みの端末を選びます
- 支払いを開始: 支払いを開始をクリックします — Squareがチェックアウトをデバイスへプッシュします
- 顧客の支払い: 顧客がSquare Terminalでカードをタップ、挿入、またはスワイプします
- 完了: 待機中はステータスがライブで更新され、Squareが支払いを確認すると注文は支払い済みとしてマークされます
Sandboxでは、デバイス一覧にSquareが文書化しているテスト用デバイスIDが含まれるため、成功、タイムアウト、オフラインといったあらゆる結果をハードウェアなしで試せます。
支払いコントロール
- 支払いを開始: 選択した端末に新しい支払いリクエストを送信します
- 支払いをキャンセル: 端末で進行中の支払いをキャンセルします
- ステータスを確認: Squareに現在の状態をすぐに問い合わせます
- 支払いを解放: 応答しない端末を切り離し、注文を別の方法で支払えるようにします。放棄されたチェックアウトはバックグラウンドで照合されます
- 支払いログ: Squareでの各ステップと結果を記録する、注文ごとの任意のログです
注文管理
- 検証済みの完了処理: 注文が支払い済みとしてマークされるのは、SquareのPaymentオブジェクトに対して支払いが検証された後のみです。検証されていないシグナルでマークされることはありません
- 支払い追跡: Square識別子と支払いログが注文に保存され、主要なステップは注文メモに書き込まれます
- レシート生成: 支払い成功後、標準のPOSレシートが生成されます
要件
ハードウェア互換性
Square TerminalはSquareのサーバー側Terminal APIを使用します。チェックアウトはサイトによって作成され、Squareからペアリング済みデバイスへ配信されます。端末はオンラインで、プラグインと同じSquareアカウントおよびロケーションにサインインしている必要があります。
対応端末
- Square Terminal ✅ — Square専用のカウンター設置型カード端末
範囲と制限
- POS / order-payフローに重点を置いています。顧客向けストアフロントのチェックアウトではデフォルトで無効であり、明示的に有効化する必要があります。
- 支払いの回収のみを行います — 返金はまだサポートされていません。Square識別子は注文に保存されるため、返金サポートは後から追加できます。
- WebhookのサブスクリプションはSquareで手動で追加する必要があります。Webhookを参照してください。
トラブルシューティング
よくある問題
Terminal Deviceの一覧が空です
- まずTerminalをこのプラグインとペアリングする必要があります — Create Device Codeを使い、デバイスにコードを入力してください
- Square DashboardやSquare POSアプリ経由でペアリングされたTerminalは、ここでペアリングするまで表示されません
- Check for readersをクリックしてください。Other devices Square can seeに表示される場合、デバイスは存在しますが、このプラグインとはペアリングされていません
- Location IDが、Terminalがサインインしているロケーションと一致していることを確認してください
デバイスをペアリングできない
- デバイスコードの有効期限が切れる前に入力したことを確認してください — Create Device Codeで新しいコードを生成します
- 端末がオンラインで、プラグインと同じSquareアカウントおよびLocation IDにサインインしていることを確認します
- 環境が、端末でサインインしているアカウントと一致していることを確認します
設定の検証に失敗する
- 接続している場合は、Square accountの行にConnected to Squareと表示されているか確認してください。再接続を求められる場合は、認証が失効しています
- アクセストークンを使用している場合は、選択した環境と一致していることを確認します（SandboxトークンはProductionでは機能せず、その逆も同様です）
- Location IDがそのアカウントに属していることを確認します
端末では支払いが完了するが、注文の更新が遅い
- これはwebhookで解決できる問題です。webhookがない場合、注文はポーリングまたはバックグラウンドの照合処理が次に実行されたときに更新されます
- Webhooksの行を確認してください。支払いを実行した後もNot verified yetと表示される場合は、Webhookの検証が通らなくなった場合に従ってください
- 注文が失われることはありません。ポーリングが取りこぼした支払いは、照合処理が調整します
支払いを開始できない
- 端末が選択されており、デバイスがペアリング済みかつオンラインであることを確認します
- デバイスが設定済みのLocation IDにサインインしていることを確認します
- 支払いログと
WooCommerce > Status > LogsでSquare APIメッセージを確認します
Squareへの再接続が必要と表示される
Squareの認証は自動的に更新されます。更新が完了できない場合、プラグインは使用できない状態のまま放置せずに認証を終了し、設定画面で再接続を求めます。Reconnect to Squareをクリックしてください。他に変更すべきものはありません。
ヘルプを得る
技術サポートについて:
- 問題を報告するにはGitHubリポジトリにアクセスしてください
- ハードウェアとAPIのガイダンスについてはSquare Terminal APIドキュメントを確認してください
- アカウントやハードウェアの問題についてはSquareサポートに連絡してください
ログはWooCommerce > Status > Logsのsqtwcハンドルの下に書き込まれ、各デバイスの照会とwebhookの結果が記録されます。
スクリーンショット
スクリーンショットは今後の更新で追加され、次の内容を示します:
- Square account、Terminal、Advanced settingsの各セクション
- WCPOS設定でのゲートウェイ有効化
- POSチェックアウトでの支払い処理ワークフロー