Square Terminal 連携リファレンス（V1）

• 調査日: 2026-10-29
• データ時点: 2026年10月（Square Developer 公式ドキュメント）
• 親: README.md / 設計: design.md

本ドキュメントは、V1 で使う Square API の範囲と、実装時に踏みやすい落とし穴をまとめたもの。

1. できること / できないこと

Terminal は「カード読み取り＋画面表示＋印刷」の端末であり、POS ではない。商品選択・在庫・カートは外部（本設計では PWA + BE）が持つ。 現金は Terminal では扱えない。Payments API で記録する（§3.4）。

2. ペアリング

手順

1. POST /v2/devices/codes（Devices API）
   • device_code.product_type = "TERMINAL_API"
   • device_code.location_id = {locationId}
   • device_code.name = "Counter 1" など
2. 返却された 6文字の device code を端末に入力（5分以内）
3. 端末がサインイン → device.code.paired webhook
4. DeviceCode.device_id を保存（以降のチェックアウトで使用）

注意

• Dashboard で作った device code は Terminal API では使えない。必ず CreateDeviceCode で発行する
• device_id は「端末底面のシリアル番号」と対応する。API では device:995CS397A6475287 のように接頭辞付きで返る場合がある
• チェックアウトの device_id には シリアル番号を直接指定してもよい
• 端末は同時に1つの POS アプリとしかペアリングできない。Square POS（スタンドアロン）との併用は不可
• ペアリングを解除するには端末側でサインアウトする

端末IDの確認方法

• ListDevices は merchant スコープ（そのアカウントの端末のみ）で beta
• シリアルとの照合は attributes.manufacturers_id を使う
• 端末IDを自分で組み立てず、API の返値を使う

3. 注文 → チェックアウト

3.1 Order の作成（Orders API）

POST /v2/orders
{
  "idempotency_key": "{orderId}",
  "order": {
    "location_id": "{locationId}",
    "line_items": [
      { "catalog_object_id": "{variationId}", "quantity": "2" }
    ]
  }
}

• line_items[].catalog_object_id には バリエーションID（CatalogItemVariation）を指定する
• 自由入力の明細にすると「カスタム金額」扱いになり、商品別集計・在庫減算から外れる
• order.state が OPEN であること
• レスポンスの order.total_money が確定額（税込み）

3.2 Terminal Checkout の作成

POST /v2/terminals/checkouts
{
  "idempotency_key": "{orderId}-{attempt}",
  "checkout": {
    "amount_money": { "amount": 2400, "currency": "JPY" },
    "reference_id": "{orderId}",
    "note": "注文 {orderId}",
    "order_id": "{squareOrderId}",
    "device_options": {
      "device_id": "{deviceId}",
      "show_itemized_cart": true,
      "skip_receipt_screen": false
    },
    "deadline_duration": "PT2M"
  }
}

• amount_money は Order の total_money と一致させる（autocomplete=true の前提）
• show_itemized_cart: true は order_id があるときのみ有効
• reference_id に自社の注文IDを入れる（当社IDとSquare IDの対応管理用）
• deadline_duration は省略可（既定 5分）。短くして放置を防ぐ
• Square Order は注文につき1回だけ作成（冪等キー = orderId）。checkout は試行ごとに作成（冪等キー = orderId-attempt）
• 取消・拒否後の再試行では既存の Square Order を再利用する（再作成すると二重注文になる）

レスポンス / 状態

• 完了時は必ず payment_ids を取得し、GET /v2/payments/{id} で status と amount_money を検証する
• COMPLETED でも金額が一致するとは限らない（部分決済・チップ等）ため、実額を確認する
• COMPLETED/CANCELED の checkout は30日で削除される。payment_ids は自前DBに永続保存する

3.3 Webhook

署名検証

• ヘッダ Square-Signature に Base64 の HMAC-SHA256 が入る
• 計算対象は 通知URL + 生のリクエストボディ
• 署名キーは Developer Console で取得（環境ごとに異なる）
• 生ボディを使う（JSON パース後の再シリアライズでは検証できない）
• event_id で冪等化する
• CloudFront 経由で受ける場合、/webhooks/* はキャッシュ無効・全ヘッダー転送・ボディ素通しにする（署名検証のため）

3.4 現金（Terminal 外）

Terminal は現金を受け付けない。現金は Payments API で記録する。

POST /v2/payments
{
  "idempotency_key": "{orderId}-cash-{attempt}",
  "source_id": "CASH",
  "location_id": "{locationId}",
  "order_id": "{squareOrderId}",
  "amount_money": { "amount": 2400, "currency": "JPY" },
  "cash_details": {
    "buyer_supplied_money": { "amount": 10000, "currency": "JPY" }
  }
}

• レスポンスの cash_details.change_back_money が釣銭
• order_id を紐付けると、注文・在庫・レポートに反映される
• PayOrder を使う場合は autocomplete=false（Payment.status=APPROVED にする）
• ドロワーは API で開けられない。Square Terminal のドロワー対応は Square POS アプリ（スタンドアロン）の機能で、Terminal API モードでは自動開放されない。手動ドロワーか Square POS 併用で対応する
• 返金は Refunds API / Dashboard で記録（現金の受け渡しは店舗）。端末ロックは不要（Terminal を使わない）

4. 日本固有の事項

5. Sandbox とテスト

基本

• ベースURL：https://connect.squareupsandbox.com（本番は https://connect.squareup.com）
• 認証情報・アカウントは本番と完全分離
• 無料・API 呼び出し無制限・決済手数料なし
• Sandbox のテスト加盟店アカウントは日本拠点も作成可能

制約

• Devices API による実機ペアリングは不可（ハードは Sandbox で使えない）
• Terminal API の シミュレート端末ID を使ってチェックアウトを再現する
• 端末画面の UI（明細・レシート）は確認できない（自動完了）
• Sandbox Dashboard は機能限定（領収書なし、返金発行不可 等）

シミュレート端末ID（Terminal checkouts）

• 成功系は概ね $25 相当まで。テストは少額で行う
• Sandbox の Location はアプリごとに1つ（Developer Console の Locations で確認）

テスト手順（推奨）

1. Sandbox：カタログ → Order → Checkout → Webhook → 状態遷移
2. 本番：実機ペアリング → 小額決済 → 明細表示 → レシート → Dashboard 反映

6. よくあるエラー

• 実際のエラーは errors[].code を見る（API バージョンで変わる）
• 完了済み checkout は再利用できない。状態確認 → 必要なら取消 → 新規作成の順
• カード拒否時にいきなり新規 checkout を作ると、直前の決済が成立していた場合に二重課金になり得る。必ず Payment の有無を確認する
• 取消は完了前のみ有効。完了後の返金は Refunds API（Interac 以外）

7. 運用上の注意

• 端末ソフトウェアは自動更新される。更新中・再起動中は決済できないことがあるため、営業時間外の更新を前提に運用する（詳細は端末設定・公式サポートで確認）
• 更新を受け取れるよう、電源を切らずにネットワーク接続しておく運用が望ましい
• 1端末は同時に1チェックアウト。複数レジは端末ごとにペアリングする
• 明細表示は「表示のみ」。金額の正は amount_money と order.total_money
• レシートは端末内蔵プリンタ。ペアリング中は外部プリンタ不可

8. 参照

• Terminal API Overview
• Take Payments for Orders
• CreateTerminalCheckout
• POS Application Pairing
• Sandbox
• Test in Sandbox（Terminal API）
• Develop for Japan
• E-Money Payments
• PayPay QR Code Payments