Square OAuth接続
店舗や出店者ごとにSquareアカウントを接続し、決済先を分けます。
Square OAuth接続は、システム内の店舗、支店、出店者、加盟店ごとにSquareの販売者アカウントを認可し、その店舗に紐づく決済先でカード決済を行うための機能です。Roundtableでは「誰の売上として決済するか」「どの店舗で認可するか」「接続済み状態をどこで確認するか」を先にそろえると、複数事業者を扱う決済導線を設計しやすくなります。
この機能でできること
管理側の店舗一覧や出店者一覧からSquare接続を開始し、認可完了後に販売者ID、店舗ID、アクセストークン、更新トークン、有効期限を対象店舗へ保存できます。公開側の申込、注文、予約、月額決済では、注文に紐づく店舗の接続情報を使って決済先を切り替えられます。
アプリ共通のSquare設定と、店舗ごとの接続情報を分けて扱います。
SquareのApplication IDやSecretはシステム設定に置き、OAuthで取得した販売者ごとの情報だけを店舗側へ保存すると、複数店舗の決済先を安全に分けられます。
よくある利用場面
モールや加盟店ごとに売上先を分ける
本部システムは同じでも、注文ごとに出店者のSquareアカウントへ決済を通します。
店舗単位の予約決済に使う
予約対象店舗を選んだら、その店舗が接続したSquareアカウントとLocationで支払いを受けます。
接続状況を管理画面で確認する
接続済み、未接続、期限更新が必要、Location未取得などを店舗一覧で確認し、再接続の案内につなげます。
プロンプト例
接続対象の単位、保存する項目、認可開始ボタン、コールバック後の戻り先、公開決済での使い方、未接続時の扱いをまとめて伝えると、実装範囲を決めやすくなります。
プロンプト
店舗管理にSquare OAuth接続を追加してください。店舗一覧の各行にSquare接続ボタンを置き、認可完了後に店舗レコードへSquare販売者ID、Location ID、アクセストークン、更新トークン、有効期限を保存してください。公開予約決済では予約の店舗IDから接続情報を取得し、その店舗のSquareアカウントで決済してください。未接続店舗では決済へ進ませず、管理側に接続が必要な状態として表示してください。
この機能を使うときのポイント
接続単位店舗、支店、出店者、加盟店など、どのレコードにSquare認可結果を持たせるかを決めます。
共通設定と店舗情報の分離Application IDやSecretはシステム共通、OAuthで得た販売者情報は店舗ごとに保存します。
未接続時の導線公開側で決済できない場合の表示、管理側で再接続を促す表示、担当者通知の要否を決めます。
更新期限と再接続トークン期限、更新失敗、Location未取得、販売者変更時にどう再接続するかを運用として決めます。
この機能を実装するときのコツ
OAuth開始時は対象店舗をstateなどで識別し、コールバック時に改ざんされていないことを確認してから認可コードをトークンへ交換します。取得したトークンは店舗レコードへ保存し、決済時は注文や予約の店舗IDから該当店舗のLocation IDとトークンを読み込みます。SquareのRedirect URLは登録値と完全一致させ、SandboxとProductionのURL差分を混同しないようにします。コールバック完了後はJSONを直接見せず、通常の管理画面へ戻して接続済み状態を確認できるようにすると、運用担当者が迷いにくくなります。