Squareでできること・できないこと

この章でわかること

この章では、Squareで何ができるのか、そして何をSquareに任せすぎないほうがよいのかを整理します。

Squareには、ECに使える機能がたくさんあります。

たとえば、決済ページを作る機能、支払いを処理する機能、注文を管理する機能、商品や在庫を扱う機能、決済完了を通知するWebhookなどです。

ただし、最初から全部を覚える必要はありません。

この章の目的は、Square APIを細かく暗記することではありません。

大切なのは、

どの機能が、ECシステムのどの場面で使われるのかを理解することです。

攻略本のように考えるなら、Square APIは「道具箱」です。

最初からすべての道具を使いこなす必要はありません。

まずは、最初のステージを攻略するために必要な道具だけ覚えます。

---

2.1 SquareアカウントとDeveloper Dashboard

Square APIを使うには、Squareアカウントと開発者向けの設定が必要です。

Squareには、通常の管理画面とは別に、開発者向けのDeveloper Consoleがあります。

ここで、API連携に必要なアプリケーションを作成し、認証情報を確認します。

Square公式ドキュメントでは、Developer Console上でアプリケーションを作成し、Sandbox用のApplication IDやAccess Tokenを確認する手順が案内されています。(developer.squareup.com)

最初に覚えるべき情報は、次の3つです。

Application ID
Access Token
Location ID

Application ID

Application IDは、Square上で作成したアプリケーションの識別子です。

Web Payments SDKなど、一部の機能で使います。

Access Token

Access Tokenは、Square APIを呼び出すための鍵です。

この値を使うことで、Next.js側からSquare APIへリクエストできます。

Square公式では、各アプリケーションには本番環境用のPersonal Access Tokenと、Sandbox環境用のAccess Tokenが用意されると説明されています。Access TokenはSquareアカウント内のリソースへアクセスできる重要な認証情報です。(developer.squareup.com)

重要なのは、

Access Tokenをブラウザ側に出してはいけないということです。

Next.jsで使う場合は、必ずサーバー側で扱います。

よい例
↓
Route HandlerやServer ActionでAccess Tokenを使う

悪い例
↓
Client ComponentにAccess Tokenを書く

Location ID

Location IDは、Square上の店舗や事業所を表すIDです。

Squareでは、売上や在庫、決済がどの店舗に紐づくかをLocationで管理します。

Sandbox環境にもテスト用のLocation IDがあります。Square公式では、SandboxのLocation IDはDeveloper ConsoleのLocationsページで確認できるほか、Locations APIでも取得できると説明されています。(developer.squareup.com)

EC開発では、このLocation IDを使って、どの店舗・事業者の決済として扱うかを指定します。

---

2.2 Square APIの全体像

Square APIには多くの種類があります。

最初に覚えるべき代表的なものは、次の通りです。

Checkout API
Payment Links
Web Payments SDK
Payments API
Orders API
Catalog API
Inventory API
Customers API
Webhooks

名前だけ見ると難しく感じますが、役割を分ければシンプルです。

機能	役割
Checkout API	Square側の決済ページを作る
Payment Links	支払い用リンクを作る
Web Payments SDK	自社サイト内に安全な決済入力UIを置く
Payments API	支払いを作成・管理する
Orders API	注文情報を扱う
Catalog API	商品情報を扱う
Inventory API	在庫情報を扱う
Customers API	顧客情報を扱う
Webhooks	決済完了などのイベント通知を受け取る

本書では、最初からすべてを使いません。

最初に使うのは、主に次の3つです。

Checkout API
Payment Links
Webhooks

この3つを使えば、最小構成のECを作れます。

商品ページ
↓
購入ボタン
↓
Square決済ページ
↓
決済完了
↓
Webhookで注文確定

まずはここを目指します。

---

2.3 Checkout APIとは

Checkout APIは、Squareが用意する決済ページを作るためのAPIです。

Square公式では、Checkout APIは、SquareがホストするチェックアウトページのURLを取得し、購入者が商品やサービスの支払いを行えるようにするAPIとして説明されています。(developer.squareup.com)

簡単に言うと、

自分のECサイトからSquareの決済ページへ送るための機能です。

流れは次のようになります。

1. ユーザーが商品ページを見る
2. 購入ボタンを押す
3. Next.js側でCheckout APIを呼ぶ
4. Squareの決済ページURLを受け取る
5. ユーザーをSquare決済ページへ移動させる
6. Square側で支払いが完了する
7. 自分のサイトへ戻る

初心者にとって、Checkout APIは非常に扱いやすい入口です。

なぜなら、カード入力画面を自作しなくてよいからです。

自作しないもの
↓
カード番号入力欄
有効期限入力欄
セキュリティコード入力欄
決済画面の安全性管理

これらをSquare側に任せられます。

最初のECでは、まずCheckout APIを使うのがおすすめです。

---

2.4 Payment Linksとは

Payment Linksは、支払い用のリンクを作る仕組みです。

SquareのCreatePaymentLink APIでは、購入者が支払いできるSquareホスト型の決済ページを作成できます。APIリファレンス上でも、CreatePaymentLinkはSquare-hosted checkout pageを作成するエンドポイントとして説明されています。(developer.squareup.com)

イメージは、とてもシンプルです。

支払いリンクを作る
↓
そのリンクをユーザーに開いてもらう
↓
Squareのページで支払ってもらう

たとえば、次のような使い方ができます。

商品ページの購入ボタンから決済リンクを作る
メールで決済リンクを送る
LINEで個別の決済リンクを送る
管理画面から支払いリンクを発行する
催事後に個別決済リンクを送る

Payment Linksは、最小構成のECと相性が良いです。

特に、小規模事業者や実店舗がオンライン販売を始める場合、最初の一歩として使いやすい機能です。

攻略ポイント

最初は、カート機能を作らなくても構いません。

商品詳細ページに購入ボタンを置き、押されたらPayment Linkを作成する。

これだけで、かなりシンプルな販売導線が作れます。

商品詳細ページ
↓
購入ボタン
↓
Payment Link作成
↓
Square決済ページ

まずはこの流れを作ることが、第1ステージです。

---

2.5 Web Payments SDKとは

Web Payments SDKは、自社サイト内に安全な決済入力UIを置くための仕組みです。

Square公式では、Web Payments SDKは、ブラウザ上で安全なカード入力方法やその他の安全な支払い方法を提供するJavaScript SDKとして説明されています。(developer.squareup.com)

Checkout APIとの違いは、決済画面の場所です。

Checkout API
↓
Square側の決済ページで支払う

Web Payments SDK
↓
自社サイト上でカード情報を入力する

Web Payments SDKを使うと、購入体験をより自由に作れます。

たとえば、

カート画面の中でそのまま決済したい
ブランドのデザインを崩さずに決済したい
自社サイト内で購入体験を完結させたい
会員機能と決済を細かく連携したい

という場合に使います。

ただし、最初から使う必要はありません。

Web Payments SDKは便利ですが、Checkout APIよりも実装の理解が必要です。

本書では、まずCheckout APIとPayment LinksでECの基本を作ります。

その後、応用編でWeb Payments SDKを扱う流れにします。

---

2.6 Payments APIとは

Payments APIは、支払いを作成・管理するためのAPIです。

Squareのオンライン決済概要では、Web Payments SDKでカード情報を安全に収集し、Payments APIでカード決済を処理する構成が紹介されています。(developer.squareup.com)

Web Payments SDKとPayments APIの関係は、次のように考えるとわかりやすいです。

Web Payments SDK
↓
カード情報を安全にトークン化する

Payments API
↓
そのトークンを使って支払いを作成する

Square公式のWeb Payments SDKのカード決済手順でも、Card.tokenize()で支払いトークンを生成し、そのトークンをサーバー側のCreatePayment処理に渡す流れが説明されています。(developer.squareup.com)

つまり、Payments APIは本格的な決済処理で使うAPIです。

初心者向けの考え方

最初の段階では、Payments APIを直接使わなくても大丈夫です。

まずはCheckout APIでSquare側の決済ページを使います。

その後、次のような要件が出てきたらPayments APIを検討します。

自社サイト内で決済を完結させたい
決済画面を完全にカスタマイズしたい
カートと決済を一体化したい
より細かく支払い処理を制御したい

攻略順としては、次の流れがおすすめです。

初級
↓
Checkout API / Payment Links

中級・上級
↓
Web Payments SDK + Payments API

---

2.7 Orders APIとは

Orders APIは、注文情報を扱うためのAPIです。

ECにおける注文とは、単なる支払い金額ではありません。

次のような情報を含みます。

何を買ったか
いくつ買ったか
税込か税抜か
送料はいくらか
割引はあるか
合計金額はいくらか
支払い済みか
キャンセルされたか

Square公式では、Orders APIは購入アイテムの記録、合計金額の計算、支払い確認、注文の進行管理、在庫更新などに使えるAPIとして説明されています。(developer.squareup.com)

Orders APIを使うと、Square側に注文情報を持たせることができます。

たとえば、次のような構成です。

Next.jsで商品を選ぶ
↓
Square Orders APIで注文を作る
↓
Checkout APIで決済リンクを作る
↓
Square上で支払い
↓
注文ステータスを確認

ただし、本格的な注文管理をする場合は、Squareだけに頼るか、自前DBにも注文を保存するかを考える必要があります。

本書では、実務を考えて、

Squareの注文情報と自前DBの注文情報を対応づける設計を扱います。

---

2.8 Catalog APIとは

Catalog APIは、Squareの商品情報を扱うためのAPIです。

Square公式では、Catalog APIを使うことで、販売者の商品ライブラリをプログラムから管理でき、商品作成、表示、更新、削除などができると説明されています。(developer.squareup.com)

Catalogは、いわゆる商品マスターです。

商品名
商品カテゴリ
商品バリエーション
価格
オプション
販売対象かどうか

Square POSを使って実店舗でも販売している場合、Square上の商品情報をECでも使いたくなることがあります。

その場合、Catalog APIが役立ちます。

ただし、Next.jsでブランド性の高いECを作る場合、商品ページの情報をすべてSquare Catalogだけで管理するのは難しいことがあります。

たとえば、次のような情報です。

長い商品説明
ブランドストーリー
作り手の紹介
SEO用の本文
複数の写真構成
ギフト向け説明
レシピや使い方

これらは、Squareよりも自前DBやCMSで管理したほうが扱いやすい場合があります。

攻略ポイント

Catalog APIは、商品販売に関わる基本情報を扱う道具です。

一方で、商品の魅力を伝えるページ作りはNext.js側で行います。

Square Catalog
↓
商品名・価格・バリエーションなど

Next.js / CMS
↓
商品説明・写真・SEO・ブランド表現

このように分けると、実務で管理しやすくなります。

---

2.9 Inventory APIとは

Inventory APIは、在庫情報を扱うためのAPIです。

Square公式では、Inventory APIはSquare販売者の在庫をプログラムから管理するAPIであり、在庫数量の調整や在庫変動の確認に使えると説明されています。(developer.squareup.com)

ECで在庫管理をする場合、次のようなことを考える必要があります。

現在いくつ在庫があるか
購入されたら在庫を減らす
売り切れになったら購入できないようにする
実店舗とECの在庫をどう同期するか
催事販売とオンライン販売をどう両立するか

SquareのInventory APIを使えば、Square側の在庫と連携できます。

また、Square公式では、Square APIやSquareハードウェアで商品明細付きの支払いを処理する場合、在庫追跡が有効な商品バリエーションの数量は自動更新されると説明されています。ただし、その他の在庫変動は手動で調整が必要です。(developer.squareup.com)

つまり、Inventory APIは便利ですが、在庫設計は慎重に行う必要があります。

特に重要なのは、

在庫の正本をどこに置くかです。

Squareを正本にする
↓
実店舗・POSとの連携に強い

自前DBを正本にする
↓
EC独自の在庫管理に強い

最初は厳密な在庫表示をしない
↓
少量販売・受注販売・手動確認向け

在庫管理は、EC開発の中でも難易度が高い領域です。

最初から複雑にしすぎないことが大切です。

---

2.10 Customers APIとは

Customers APIは、顧客情報を扱うためのAPIです。

Square API Referenceでは、Customers APIは顧客プロフィールを作成・管理し、CRMシステムとの同期などに利用できるAPIとして説明されています。(developer.squareup.com)

顧客情報には、次のようなものがあります。

名前
メールアドレス
電話番号
購入履歴
顧客ID
メモ
顧客グループ

ECでは、顧客情報を使って次のようなことができます。

注文履歴を表示する
再購入しやすくする
リピーターを管理する
メール配信と連携する
問い合わせ対応をしやすくする

ただし、顧客情報は慎重に扱う必要があります。

個人情報を必要以上に保存すると、管理責任が重くなります。

最初のECでは、顧客管理を複雑にしすぎないほうが安全です。

攻略ポイント

最初は、注文に必要な最低限の顧客情報だけ扱います。

購入者名
メールアドレス
配送先
注文内容

会員機能や詳細なCRMは、必要になってから追加すれば大丈夫です。

---

2.11 Webhookで受け取れるイベント

Webhookは、Square側で何かが起きたときに、自分のシステムへ通知してもらう仕組みです。

Square公式では、Webhookは在庫変更やPOS決済などのイベントについて、リアルタイム通知を受け取るための仕組みとして説明されています。(developer.squareup.com)

ECで特に重要なのは、決済完了の通知です。

フロントエンドの画面だけで「支払い完了」と判断してはいけません。

理由は、ユーザーの画面遷移は信用しきれないからです。

たとえば、次のようなことが起こります。

支払い後にブラウザを閉じる
通信が途中で切れる
完了ページに戻る前に離脱する
戻るボタンを押す
同じ画面を再読み込みする

そのため、注文確定はWebhookをもとに行います。

代表的な流れは次の通りです。

ユーザーがSquare決済ページで支払う
↓
Square側で支払いが更新される
↓
SquareからWebhookが届く
↓
Next.js側で支払い状況を確認する
↓
注文を確定する
↓
在庫を減らす
↓
メールを送る

Payments APIでは、支払いが作成または更新されたときにWebhookイベントを受け取ることができ、支払い完了時にはpayment.updatedイベントが生成される例が公式ドキュメントで示されています。(developer.squareup.com)

Webhookには、支払いだけでなく、注文、在庫、商品、顧客などに関するイベントもあります。

Square公式のWebhook Events Referenceでは、購読可能なイベントがAPI別に整理されています。(developer.squareup.com)

注意点

Webhookは、同じイベントが複数回届く可能性があります。

そのため、Webhookを受け取ったら毎回処理するのではなく、

すでに処理済みかどうかを確認する設計が必要です。

Webhookを受け取る
↓
イベントIDやPayment IDを確認する
↓
すでに処理済みなら何もしない
↓
未処理なら注文を確定する

これを冪等性と呼びます。

最初は難しく感じますが、本格ECではとても重要な考え方です。

---

2.12 Squareで在庫管理まで行うべきか

Squareで在庫管理まで行うべきかは、事業の形によって変わります。

答えは一つではありません。

次のように考えると判断しやすくなります。

Squareで在庫管理するのが向いているケース

Square POSを実店舗で使っている
実店舗とECの在庫を連動させたい
商品数が比較的シンプル
Square上の商品マスターを中心に運用したい
店舗スタッフもSquareで在庫を見る

この場合は、SquareのCatalog APIやInventory APIを活用する価値があります。

実店舗販売とオンライン販売の在庫を近づけやすくなります。

自前DBで在庫管理するのが向いているケース

EC独自の商品構成が多い
セット販売やギフト商品が多い
予約販売や受注生産がある
在庫表示を独自ルールで制御したい
管理画面を自社業務に合わせたい

この場合は、自前DBで在庫を管理したほうが柔軟です。

ただし、自前DBで管理する場合は、Square側の注文や決済とズレないように設計する必要があります。

最初は在庫を厳密に出さない選択肢もある

小規模ECでは、最初から在庫数を厳密に表示しない方法もあります。

在庫あり
残りわずか
売り切れ
予約受付中

このような状態表示だけにして、細かい在庫数は管理者側で確認する方法です。

少量販売や催事販売では、このほうが現実的な場合もあります。

攻略ポイント

在庫管理は、最初から完璧を目指さないことです。

まずは次のような段階で考えます。

レベル1
在庫表示なしで販売する

レベル2
売り切れ表示だけ実装する

レベル3
自前DBで在庫数を持つ

レベル4
Square Inventory APIと連携する

レベル5
実店舗・催事・ECを統合管理する

いきなりレベル5を目指すと、開発が止まりやすくなります。

最初は、販売開始を優先します。

---

2.13 Squareと自前DBの責務分担

本格的なECを作るときに重要なのが、Squareと自前DBの責務分担です。

Squareにも注文、商品、在庫、顧客の情報を持たせることができます。

一方で、Next.js側の自前DBにも、注文や商品情報を保存できます。

ここで問題になるのが、

どちらを正しい情報として扱うのかです。

Squareに任せるべき情報

Squareに任せるべきなのは、決済に関する情報です。

支払いID
支払いステータス
決済金額
決済日時
決済方法
返金情報

決済の正しさはSquare側を基準にします。

自前DBに「支払い済み」と書いてあっても、Square側で支払いが完了していなければ、支払い済みとして扱ってはいけません。

自前DBに持つべき情報

自前DBには、ECサイト運用に必要な情報を保存します。

自社側の注文ID
商品ページ用の商品情報
注文者情報
配送先情報
注文ステータス
発送ステータス
管理メモ
メール送信履歴
在庫表示用の情報

特に、管理画面や配送処理を作る場合、自前DBがあると便利です。

Squareだけで完結させようとすると、独自の業務フローを作りにくくなることがあります。

おすすめの責務分担

本書では、次の責務分担をおすすめします。

領域	主担当	理由
決済処理	Square	安全性と信頼性が重要
決済ステータス	Square	支払いの正本として扱う
商品ページ	Next.js / 自前DB / CMS	SEOやブランド表現が必要
注文管理	自前DB + Square連携	管理画面や配送処理に必要
在庫管理	初期は自前DBまたは簡易管理	事業により最適解が変わる
顧客管理	最初は最小限	個人情報を持ちすぎない
Webhookログ	自前DB	障害対応と二重処理防止に必要

実務では、次のような流れにします。

1. 自前DBに仮注文を作る
2. Squareで決済リンクを作る
3. ユーザーがSquareで支払う
4. Webhookで決済完了を受け取る
5. Squareの支払い状況を確認する
6. 自前DBの注文を支払い済みにする
7. 在庫を更新する
8. メールを送る

この流れにすると、Squareと自前DBの役割がはっきりします。

攻略ポイント

Squareは、決済の正本です。

自前DBは、EC運用の正本です。

Square
↓
支払いが本当に完了したかを見る場所

自前DB
↓
自社ECとして注文をどう扱うかを管理する場所

この分担を間違えると、注文のズレや在庫のズレが起きやすくなります。

---

この章のまとめ

Squareは、ECに必要な多くの機能を持っています。

特に重要なのは、次の機能です。

Checkout API
Payment Links
Web Payments SDK
Payments API
Orders API
Catalog API
Inventory API
Customers API
Webhooks

ただし、初心者が最初からすべて使う必要はありません。

最初に覚えるべきなのは、次の3つです。

Checkout API
Payment Links
Webhooks

この3つを理解すれば、最小構成のECを作れます。

商品ページ
↓
購入ボタン
↓
Square決済ページ
↓
Webhookで注文確定

Squareに任せるべきなのは、主に決済まわりです。

Next.jsや自前DBで作るべきなのは、商品ページ、購入導線、管理画面、SEO、注文管理などです。

本書では、Squareを「全部任せるサービス」としてではなく、

安全な決済と商取引データを扱う強力な道具として使います。

---

次の章でやること

次の章では、Next.jsでECを作る基本設計を整理します。

Squareで何ができるかは見えてきました。

次は、Next.js側でどのように商品ページ、購入ボタン、API、決済完了ページ、Webhook受信処理を作るのかを見ていきます。

Next.jsには、Server Component、Client Component、Route Handler、Server Actionなどの機能があります。

名前だけ聞くと難しそうですが、ECの役割に置き換えると理解しやすくなります。

次章では、Next.jsをECサイトの「街づくり」として考えながら、基本設計を攻略していきます。