TL;DR
- SquareのSubscription APIは別に使えなくはない
- 開発環境はあまりよくない
- そもそもたぶんサブスク系をガチで実装することが想定されてない
- Stripeは開発環境がめっちゃいい
背景
スポーツジムのサブスクシステムを開発するにあたって、クライアント様から「実店舗でSquare決済を使用しているので、可能ならオンライン決済もSquareで行いたい」との要望がありました。
とりあえず調べたところ、SquareにはSubscriptionがあり、Hosted Checkoutもあり、カード情報も保存できます。
ということで初めはSquareで実装すりゃええかと思って要件を足していきました。
- 基本料金に家族プランやロッカーなどのオプションを付ける
- オプションは次回更新から反映する
- 休会中は安い料金を払い、継続期間は維持する
- 3か月続けたら基本料金だけ1か月無料にする
- 無料月でもオプションは請求する
- 支払い失敗から30日間は回復期間にする
- 退会は期間末まで利用可能にする
だんだんややこしくなってきたぞ。
Squareのサブスクはかなり分割されている
Squareの公式ドキュメントを読むと、サブスクは一つのAPIで完結するわけではないようです。
商品と料金はCatalog API、相対価格やフェーズはOrders API、請求書はInvoices API、カード決済の結果はPayments APIです。Subscription自体の変更予定はActionとして管理され、Webhookにはsubscription.createdやsubscription.updatedが届きます。請求の成功や失敗は、InvoiceやPayment側も見ないと判断できません。
会員を「支払い済み」と判定するだけでも、Subscriptionの状態、予約されたPAUSEやRESUME、発行されたInvoice、Invoiceに紐づくPayment、Paymentの成功または失敗を突き合わせる必要があります。
これが非常にややこしくて、Squareの状態と自社の状態を同期するためにかなりの処理が必要になります。
そもそもSquareのサブスク決済はSquare有料プランにしか搭載されておらず、あまりガチで使用されることを想定していない印象を受けました。
休会←とてもむずかしい
SquareにはPauseSubscriptionがあります。
現在の請求期間の末尾にPAUSEを予約して、指定したサイクル数だけ休会できます。これはかなり便利です。
ただ、今回の要件では「休会」というのは「休会中も安い料金を払って、継続特典だけ維持する」仕組みだったので、通常プランとは別に休会用のPlan Variationを作り、次回更新前に切り替えることにしました。
再開するときは元のVariationに戻すかんじです。
ただ、ここで問題があります。SquareのPlan Variationは、作成後にフェーズを追加、削除、並べ替えできません。料金や割引の構成を変えたければ、新しいVariationを作る必要があります。
これの何が問題かというと、管理ダッシュボード的なものを作って柔軟に料金構成を変えることが非常に難しいのです。料金を変更するためだけに、Variationの世代管理と移行状況の管理が必要になります。ひぇ～
ローカルWebhookと時間
それでもとりあえずは(Codexが)泣きながら実装して、いざローカルでテストするぞとなったらまた問題が起きます。もちろん(?)ローカルWebhookシミュレーションなどという便利なものはないので、cloudflareでトンネル建ててWebhookを試します。
すると、決済通してもWebhookが届かない。ダッシュボードにも表示されない。全部確認しても実装に問題ないはずなのに、うまくサブスクできない。
それで少し調べたところ、こんな記事を見つけました。
Sandbox Subscriptions - Questions
Hi so developing a website that uses Square for subscriptions.
Very confused with testing so far. My application created a subscription payment link - Checkout API Sandbox Testing Panel
I have gone through the steps on this link, but I really do not see any users in the sandbox dashboard, as if the order never was paid for. I have looked through previous forums but not clear as to why the order sandbox process does not work like a regular order with a test credit card (like Stripe)?
Please advise. Thank you.
Hello [名前],
Square’s Sandbox doesn’t fully simulate subscription flows—subscription events and users aren’t created when using Checkout API links in Sandbox. Unlike Stripe, Square’s test environment lacks full parity for subscriptions. For accurate testing, use production with a $0 plan or rely on webhook simulations.
Best Regards,
[名前]
要は、Squareのサンドボックスは完全なシミュレーションではないらしいです。だからサブスク関連は再現されないよと。えぇ。
ついでに言うと、StripeのTest Clockみたいな機能もありません。そのため、サブスクが実際に更新されるかテストするために1ヶ月座って待たなくてはなりません。次回更新でオプションが有効になるか確認するとか、休会料金で請求されるか確認するとか、支払い失敗後に回復できるか確認するとか、期間末の退会で次の請求が止まるか確認するとか、全部やってたら大学卒業してしまいます。留年の可能性もあるけど。
流石にやってられません。
Stripeに移行した
最終的に、Squareで粘るのは諦めました。
Stripe CLIは最高です。Webhookをローカルへ転送できます。Test Clockで契約の時間を進められます。そして実際に作られたInvoiceを見ながら確認できます。
開発者のための環境が整っていることがこれほど素晴らしいと感じたのは久々です。自分がSaaSを提供する側になった時に意識しておきたいポイントだと感じました。