Skip to main content
できること: Stripe の支払い済み期間が終了する前に、ユーザーは Waffo でカード入力と必要な 3DS 認証を完了できます。期限前には請求せず、引き継ぎ時刻に Waffo が初回請求を自動的に開始します。待機中の状態を照会でき、引き継ぎ前に解約すれば初回請求も停止できます。 連携は 3 ステップです: WaffoStripe.client(...) へ切り替え、対象サブスクリプションにルーティングタグと引き継ぎ時刻を追加し、Waffo Webhook を接続します。既存の com.stripe.* 型と呼び出し方法は維持できます。クイックスタートにコード変更全体を示します。本番利用前には、連携ガイドに従って冪等キーとサブスクリプションの対応関係も永続化してください。
現在利用できるのは Java 版の com.waffo:waffo-java-stripe です。Node.js、Python、Go 版は今後提供予定です。

Waffo ネイティブ SDK との違い

Waffo には異なる 2 つの連携方法があります。先に用途に合う方を確認してください。 新規連携ではネイティブ SDKを使用してください。 このアダプターは、すでに Stripe 上でサブスクリプションを運用しており、コード変更のコストを抑えたい場合に適しています。

移行ツールの役割

ルーティング

リクエストごとに Waffo へ送るか Stripe へそのまま送るかを判断するため、呼び出し側に分岐は不要です。

パラメーター変換

Stripe の SessionCreateParams を、金額、期間、通貨、支払い方法、Cashier の言語を含む Waffo サブスクリプション作成リクエストへ変換します。

レスポンス変換

Waffo のレスポンスを Stripe の SessionSubscription に戻すため、既存の getter をそのまま使えます。

通知変換

Waffo のサブスクリプション通知を Stripe の Event に変換し、既存の Webhook 分岐を再利用できます。

動作の仕組み

アダプターは標準の StripeClient を返し、各リクエストを次のルールで振り分けます。 タグのない呼び出しには影響しません。 1 回払い、タグのないサブスクリプション、顧客、価格の各オブジェクトは移行前と同じように動作します。一部のサブスクリプションだけを Waffo に移し、Stripe と並行運用できます。 サブスクリプション支払いは次のように進みます。
1

サブスクリプション Checkout を作成

通常どおり client.checkout().sessions().create(params) を呼び出し、paramsmetadata.source=waffo を 1 行追加します。アダプターが Waffo の作成リクエストへ変換します。
2

Cashier URL を取得

戻り値は Stripe の Session のままで、session.getUrl() に Waffo Cashier URL が入ります。既存のリダイレクト処理は変更不要です。
3

ユーザーが支払う

ユーザーは Waffo Cashier で支払いを完了します。この区間をアプリケーションが処理する必要はありません。
4

通知を受信して変換

Waffo は設定した notifyUrl に通知します。エンドポイントで WaffoStripeWebhooks.handle(...) を呼び出して WaffoStripeWebhookResult を受け取り、result.getEvent() から Stripe の Event を取得します。
5

既存のビジネスロジックを実行

switch (event.getType())customer.subscription.createdinvoice.paid を処理する既存コードをそのまま使用できます。

対応するシナリオ

初期リリースはリダイレクト型 Cashier のサブスクリプションを対象にしています。 フォールバック条件、理由コード、解約機能の境界は、連携ガイドの未対応の Stripe 利用方法を参照してください。

有効期限が近づいた Stripe サブスクリプションを Waffo へ移行

Stripe サブスクリプションの現在の支払い済み期間が時刻 T に終了するとします。既存の Stripe フローで更新を T に停止し、同じユーザー向けに T から始まる Waffo サブスクリプションを事前に作成します。
1

引き継ぎ時刻を取得

Stripe サブスクリプションから支払い済み期間の終了時刻 T を取得します。
2

Waffo の開始時刻を設定

Waffo へルーティングするリクエストで subscription_data.billing_cycle_anchorT に設定し、proration_behavior=none を指定します。
3

事前に認証

T より前にユーザーが Waffo Cashier を開き、カード入力と必要な 3DS 認証を完了します。この時点では初回料金を請求しません。
4

待機状態を確認

待機中に wsub_… を照会します。billing_cycle_anchorcurrent_period_endT と一致し、metadata.waffo_current_period=0 は最初の請求期間がまだ始まっていないことを示します。
5

引き継ぎ時に自動請求

T に到達すると、Waffo が初回請求を自動的に開始します。ユーザーの再操作は不要です。
ユーザーが T より前に移行を取り消す場合、Subscription.cancel("wsub_…") は Waffo サブスクリプションを即時解約し、予定されていた初回請求を停止します。
Stripe 移行ツールが処理するのは Waffo 側の申請、照会、解約です。元の Stripe サブスクリプションは変更しません。既存の Stripe コードまたは Dashboard を使い、同じ T に旧サブスクリプションを終了してください。

クイックスタート

以下の 3 ステップで主要なコード変更を示します。コード変更に加えて、リクエスト送信前に冪等キーを永続化し、作成後に Waffo サブスクリプション id と業務注文の対応を保存してください。以下は既存クラスへ組み込む主要部分のコード片です。

ステップ 1:クライアント生成を変更

戻り値の client は標準の StripeClient です。既存のクライアントと置き換えても、呼び出し側のコードは変わりません。

ステップ 2:ルーティングタグと冪等キーを追加

この例では uiMode を意図的に設定していません。Stripe の既定値はリダイレクト型で、移行ツールも未設定をリダイレクト型として扱います。これにより stripe-java 24.11.x、32.x、33.x で同じコードを使用できます。32.x または 33.x の HOSTED_PAGE に置き換えないでください。そのシリアライズ値 hosted_page は非リダイレクト型と判定されます。 stripe-java が自動生成する冪等キーに依存しないでください。32 文字以内の安定したキーを明示的に渡して永続化し、再試行でも同じキーを使用してください。詳細は連携ガイドを参照してください。

ステップ 3:Waffo Webhook を連携

アプリケーションには新しい HTTP エンドポイントが必要ですが、既存の Stripe Webhook は変更しません。SDK の handle(...) は署名検証、解析、イベント変換、確認レスポンスの生成まで行います。エンドポイントは、変換結果をビジネスロジックへ渡し、SDK が生成した確認レスポンスを Web フレームワークのレスポンスへマッピングします。
WaffoStripeWebhookResult には確認レスポンスの本文が含まれています。最後の数行は、それを Spring の ResponseEntity へマッピングしているだけです。別の Web フレームワークでは同等のマッピングを行ってください。詳細は連携ガイドを参照してください。

連携ガイド

設定項目、Webhook の処理方法、未対応の Stripe 利用方法、連携チェックリスト、Sandbox 検証要件を確認できます。

AI 移行スキルを使用する

Claude Code、Codex、Cursor を使用している場合は、スキャンと変更を AI に任せられます。
インストール後、プロジェクト内で AI に「Stripe を移行」と指示します。AI は Stripe の呼び出しを検出し、ルーティングできない箇所を示し、承認後にコードを変更して Sandbox 検証まで案内します。
スキャン結果はリスクを見つけるための情報であり、検証結果ではありません。どの方法で連携しても、プロジェクト自身の API から Sandbox のエンドツーエンド検証を完了してください。

バージョンと前提条件

stripe-java は provided 依存関係です。アダプターはバージョンを上げ下げしません。24.11.0 以上を使用してください。 導入前に次を確認してください。
  • Waffo とサブスクリプション契約を締結し、Sandbox 認証情報を取得している。
  • 使用する通貨が契約範囲に含まれている。paymethodconfig/inquiry で確認できます。
  • Waffo 通知を受け取る公開 HTTPS エンドポイントがある。

関連リソース