Square Terminalゲートウェイ
Square Terminalゲートウェイを使用すると、WCPOSから直接Square TerminalハードウェアでWooCommerce注文の支払いを受け付けられます。支払いはWooCommerceから要求され、ペアリング済みのSquare Terminalデバイスで完了し、その結果が注文に書き戻されます。
機能
ハードウェア統合
ペアリング済みのSquare Terminalデバイスに支払いを送信し、対面カード決済を受け付けます
簡単なペアリング
短時間だけ有効なSquareデバイスコードを使用して、WooCommerceから端末をペアリングします
Webhookによる確認
検証済みのSquare webhookが完了を確認し、待機中もライブステータスを表示します
安全な取引
Squareハードウェア上で処理される、PCI準拠のカード対面決済
Sandboxと本番環境
ライブ決済へ切り替える前にSquare Sandboxで検証します
仕組み
ブラウザーSDK型のゲートウェイとは異なり、Square TerminalはSquareのサーバー側Terminal APIを使用します。支払いを開始すると、WooCommerceが注文用のTerminal Checkoutを作成し、Squareがそれをペアリング済みデバイスへプッシュします。顧客は端末で支払い、Squareは署名付きwebhookでサイトに通知します。Webhookが信頼できる完了シグナルです。POSもポーリングを行うため、待機中にステータスが更新されます。
つまり、Square Terminalデバイスはオンラインで、同じSquareアカウントとロケーションにサインインしている必要があります。また、Squareがwebhookを配信できるように、サイトはHTTPSで公開アクセス可能でなければなりません。
インストール
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を見つけ、クリックして設定を開きます
- 環境を選択します（テストには
Sandbox、ライブ決済にはProduction） - 選択した環境（SandboxまたはProduction）のAccess Tokenを入力します。これはSquare Developer Dashboardから取得できます
- Location IDを入力します — Terminal決済を受け付けるSquareロケーションです
- Webhook Signature KeyとWebhook Notification URLを入力します（次の手順を参照）
- 設定を検証をクリックして認証情報が機能することを確認し、保存します
WooCommerce設定でSquare Terminalゲートウェイを有効化する必要はありません。後の手順でPOS専用に有効化します。
SquareでWebhookを設定
Terminal決済が完了すると、Squareは署名付きwebhookを送信します。これにより注文が支払い済みとしてマークされます。
- Square Developer Dashboardでアプリケーションを開き、Webhooksセクションに移動します
- **
terminal.checkout.updated**イベントのサブスクリプションを追加します - 通知URLをプラグイン設定に表示されているWebhook Notification URLに設定します — 完全に一致している必要があります
- 受信イベントを検証できるように、Webhook Signature Keyをプラグイン設定にコピーします
SquareのWebhook Notification URLは、プラグイン設定の値と完全に一致している必要があり、Webhook Signature Keyも正しい必要があります。一致しない場合、Squareでの支払いはデバイス上で完了しますが、WooCommerce注文は更新されません。
Square Terminalをペアリング
- 同じ設定ページでデバイスコードを作成をクリックします
- ペアリングコードが生成され、表示されます
- Square Terminalにサインインし、デバイスペアリング画面でそのコードを入力します
- ペアリングが完了すると、端末は設定済みロケーションに紐付けられます。Device IDを控えてください — 支払いを受け付けるときに入力します
支払いを処理する前に、端末が正常にペアリングされ、オンラインになっている必要があります。続行する前にペアリングが完了していることを確認してください。
WCPOSで有効化
WP Admin > POS > Settings > Checkoutに移動します- 一覧でSquare Terminalゲートウェイを見つけます
- POSで使用するためにゲートウェイを有効化します
- 設定を保存します
使用方法
支払いの処理
- アイテムを追加: POSでカートに商品を追加します
- ゲートウェイを選択: 支払い方法として「Square Terminal」を選択します
- デバイスを選択: 支払いを受け付けるペアリング済み端末のTerminal Device IDを入力します
- 支払いを開始: 支払いを開始をクリックします — Squareがチェックアウトをデバイスへプッシュします
- 顧客の支払い: 顧客がSquare Terminalでカードをタップ、挿入、またはスワイプします
- 自動完了: Squareの検証済みwebhookが支払いを確認すると、注文は支払い済みとしてマークされます。待機中はライブステータスが更新されます。
支払いコントロール
Square Terminalゲートウェイを使用すると、次の操作を行えます。
- 支払いを開始: 選択した端末に新しい支払いリクエストを送信します
- 支払いをキャンセル: 端末で進行中の支払いをキャンセルします
- 支払いステータス: ライブステータス領域に現在の支払い状態が表示されます
- 支払いログ: 注文ごとのログに、Squareでの重要な各ステップと結果が記録されます
注文管理
- Webhookを正とする完了処理: 検証済みのSquare webhookがTerminal決済を確認した場合にのみ、注文は支払い済みとしてマークされます
- 支払い追跡: Square識別子と支払いログが注文に保存され、主要なステップは注文メモに書き込まれます
- レシート生成: 支払い成功後、標準のPOSレシートが生成されます
要件
ハードウェア互換性
Square TerminalはSquareのサーバー側Terminal APIを使用します。チェックアウトはサイトによって作成され、Squareからペアリング済みデバイスへ配信されます。注文を更新するには、端末がオンラインで同じSquareアカウントとロケーションにサインインしており、サイトがHTTPSでSquare webhookを受信できる必要があります。
対応端末
- Square Terminal ✅ — Square専用のカウンター設置型カード端末
範囲と制限
- この初期リリースはPOS / order-payフローに重点を置いています。顧客向けストアフロントのチェックアウトではデフォルトで無効であり、明示的に有効化する必要があります。
- 支払いの回収のみを行います — 返金はまだサポートされていません。Square識別子は注文に保存されるため、返金サポートは後から追加できます。
トラブルシューティング
よくある問題
デバイスをペアリングできない
- デバイスコードの有効期限が切れる前に入力したことを確認してください — 必要に応じてデバイスコードを作成で新しいコードを生成します
- 端末がオンラインで、プラグインと同じSquareアカウントおよびLocation IDにサインインしていることを確認します
- 環境（Sandbox/Production）とAccess Tokenが、端末でサインインしているアカウントと一致していることを確認します
設定の検証に失敗する
- Access Tokenが選択した環境と一致していることを確認します（SandboxトークンはProductionでは機能せず、その逆も同様です）
- Location IDがそのアカウントに属していることを確認します
- 余分な文字が混入していないか確認するため、Square Developer Dashboardからトークンを再コピーします
端末では支払いが完了するが、注文が更新されない
- SquareのWebhook Notification URLは、プラグイン設定と完全に一致している必要があります
- Square Developer Dashboardで**
terminal.checkout.updated**イベントが購読されていることを確認します - プラグインのWebhook Signature KeyがSquare側のものと一致していることを確認します
- サイトがHTTPSで公開アクセス可能であることを確認し、Square Dashboardでwebhook配信試行を確認します
支払いを開始できない
- 有効なTerminal Device IDが入力され、デバイスがペアリング済みかつオンラインであることを確認します
- デバイスが設定済みのLocation IDにサインインしていることを確認します
- 支払いログとWordPressエラーログでSquare APIメッセージを確認します
ヘルプを得る
技術サポートについて:
- 問題を報告するにはGitHubリポジトリにアクセスしてください
- ハードウェアとAPIのガイダンスについてはSquare Terminal APIドキュメントを確認してください
- アカウントやハードウェアの問題についてはSquareサポートに連絡してください
スクリーンショット
スクリーンショットは今後の更新で追加され、次の内容を示します:
- Square認証情報、webhook、デバイスペアリングの構成
- WCPOS設定でのゲートウェイ有効化
- POSチェックアウトでの支払い処理ワークフロー