前提条件
- Waffo とサブスクリプション契約を締結し、Sandbox の API キー、RSA 鍵ペア、加盟店番号を取得している。
stripe-javaが 24.11.0 以上である。- Waffo 通知を受け取る公開 HTTPS エンドポイントがある。
- 使用する通貨が契約範囲に含まれている。
paymethodconfig/inquiryで確認できる。
ステップ 1:依存関係を追加
- Maven
- Gradle
stripe-java バージョンは変更しないでください。 これは provided 依存関係です。waffo-java はアダプターから推移的に導入されるため、別途宣言する必要はありません。
導入時は Maven Central で最新バージョンを確認し、
mvn dependency:get -Dartifact=com.waffo:waffo-java-stripe:<version> で解決できることを確認してから pom.xml に追加してください。ステップ 2:ルーティングクライアントを作成
new StripeClient(key) を WaffoStripe.client(...) に置き換えます。アダプター自身は Stripe のシークレットキーを保持しません。
X-Waffo-Client: waffo-stripe-java/<version> ヘッダーを自動で設定します。独自にトランスポート層を包んでこの値を作る必要はありません。
タイムアウトやプロキシを設定した既存の StripeClient がある場合は、WaffoStripe.client(routing, existingClient) でその設定を維持できます。
ステップ 3:移行対象へタグを追加
既存のパラメーター生成にmetadata を 1 行追加します。
uiMode を意図的に設定していません。Stripe の既定値はリダイレクト型で、移行ツールも未設定をリダイレクト型として扱います。これにより stripe-java 24.11.x、32.x、33.x で同じコードを使用できます。32.x または 33.x の HOSTED_PAGE に置き換えないでください。そのシリアライズ値 hosted_page は非リダイレクト型と判定されます。
有効期限が近づいた Stripe サブスクリプションを Waffo へ移行
元の Stripe サブスクリプションから現在の支払い済み期間の終了時刻を取得し、handoffAt とします。既存の Stripe フローで更新を handoffAt に停止してください。移行ツールは元の Stripe サブスクリプションを変更しません。
Waffo へルーティングするリクエストでは、同じ時刻を billing_cycle_anchor に設定し、proration_behavior=none を明示します。
billing_cycle_anchor は Waffo startTime に正確に変換されます。設定可能な最大期間は Waffo バックエンドが検証し、移行ツールは 365 日または 366 日の制限をハードコードしません。trial_end または trial_period_days と同時に設定しないでください。この組み合わせはマッピングエラーとして扱われます。Session.idはwcs_で始まり、client.checkout().sessions().retrieve("wcs_…")で取得できます。session.getSubscription()は対応するwsub_…サブスクリプション id を返し、client.subscriptions().retrieve("wsub_…")で Waffo へ自動ルーティングされます。- 作成後、
wsub_…サブスクリプション id と業務注文 ID の対応を永続化してください。Webhook 処理ではこのサブスクリプション id から業務レコードを取得し、冪等キーから注文 ID を逆算しないでください。 - Stripe の
sub_…とcs_…は引き続き Stripe へ送られます。
ステップ 4:Webhook 通知を変換
設定したnotifyUrl で handle(...) を呼び出します。SDK は署名検証、解析、イベント変換を行い、Waffo が配信確認に使用する確認レスポンスも生成します。
SDK が生成した確認レスポンスを返す
handle(...) が返す WaffoStripeWebhookResult には、確認レスポンスの本文が含まれています。SDK は Web フレームワークに依存しないため、Spring の ResponseEntity は直接返しません。Spring では次の 2 項目をマッピングし、別の Web フレームワークでは同等のマッピングを行います。
このレスポンスは、エンドポイントが通知を受信したことを Waffo に伝えます。
"ok" に置き換えると、Waffo は成功結果として認識できず、同じ通知を再送します。
署名検証に失敗した場合は、ビジネス処理を実行せず、セキュリティイベントを記録してサブスクリプション照会で状態を突合してください。
イベント対応表
変換後のデータオブジェクトは、通常どおり
event.getDataObjectDeserializer().getObject() で取得できます。
次の通知は変換されず、getEvent() は null を返します。
PAYMENT_NOTIFICATION:期間変更通知ですでにinvoice.paid/invoice.payment_failedが生成されるため、二重計上を避けます。getPaymentNotification()から別途取得し、paymentInfo.productNameでサブスクリプション課金と 1 回払いを区別してください。SUBSCRIPTION_CHANGE_NOTIFICATION:初期リリース対象外のプラン変更です。- 終端状態ではない返金通知。
従来の
translate(body, signature) はソース互換性のため残っていますが、戻り値は Event だけで、上記の確認レスポンスを取得できません。新規連携では handle(...) を使用してください。ステップ 5:即時解約を組み込む
移行ツールは Stripe の既定の解約呼び出しを使った Waffo サブスクリプションの即時解約に対応します。期間終了時解約、指定時刻での解約、サブスクリプション更新は再現しません。 まず両者の違いを整理します。
既定の解約は Waffo
subscription/cancel を呼び出し、同じサブスクリプションを照会して解約済みの最終状態を確認します。結果が不明な場合、移行ツールは同じ wsub_… の照会だけで結果を回復し、Stripe へ転送しません。handoffAt を待っている間に解約すると、予定された初回請求は発生しません。
連携チェックリスト
依存関係と設定
- Maven Central から依存バージョンを解決できることを確認した。
stripe-javaが 24.11.0 以上である。WaffoStripe.client(...)と Sandbox 設定を組み込んだ。
コード変更
- 対象リクエストに
metadata.source=waffoがあり、冪等キーを呼び出し前に永続化した。 - Webhook エンドポイントが
handle(...)を使い、SDK が生成したレスポンス本文を返す。 PAYMENT_NOTIFICATIONをサブスクリプション課金として別に処理する。- 提供処理を
checkout.session.completedからcustomer.subscription.createdとinvoice.paidへ移した。 wsub_サブスクリプションを照会して既定の即時解約を実行でき、期間終了時解約などの未対応機能に依存していない。- 同じ
handoffAtを使って Stripe の更新を停止し、Waffobilling_cycle_anchorを設定している。
検証
FAIL_LOUDが示したすべてのフォールバックを確認した。- プロジェクト自身のビルドとテストが成功した。
- Sandbox のエンドツーエンドフローを完了した。
Sandbox 検証
検証はプロジェクト自身の HTTP エンドポイントから実行してください。アダプター内部のテストだけでは不十分です。設定リファレンス
連携では同名でパッケージが異なる 2 つのWaffoConfig を使用します。
1. ルーティング設定 com.waffo.stripe.config.WaffoConfig
2. OnUnsupported の値
3. Waffo 認証情報 com.waffo.types.config.WaffoConfig
次のいずれかで作成できます。
クライアント生成と Stripe 認証情報
優先順位は、リクエスト単位の
RequestOptions キー > クライアント単位 > グローバルです。2 番目のオーバーロードが現在の stripe-java バージョンからクライアント単位の認証情報を読み取れない場合、クライアントを初期化できません。対応バージョンへ更新するか、API キーを明示的に渡すオーバーロードを使用してください。
リクエスト単位のパラメーター
未対応の Stripe 利用方法
初期リリースはサブスクリプション Checkout の一部だけを対象にします。以下は未対応の利用方法の一覧です。 「Stripe にフォールバック」と記載された行は決済に影響しません。作成リクエストは Stripe へ転送され、ユーザーは通常どおり支払えます。理由コードは戻り値のmetadata.waffo_fallback_reason に、waffo_routing=stripe_fallback とともに記録されます。この 2 つと waffo_fallback_code はアダプターの予約フィールドなので、業務コードでは使わないでください。それ以外はエラーになるか動作しなくなるため、コード変更が必要です。
既存の
si_…、sub_sched_…、sub_… は Stripe 所有を示すため、関連操作はそのまま Stripe へ送られます。
該当箇所を事前にスキャン
AI 移行スキルのスキャナーは Stripe 呼び出しを次のように分類します。
スキャナーが判定できず、手動で追う必要があるのは主に次の点です。
- パラメーターが別ファイル、ファクトリーメソッド、独自ラッパーで組み立てられている——create に実際に渡る値まで追跡し、上の表と 1 つずつ照合する。
- 変更 / 解約の対象 id の由来が不明——業務フローを辿って
wsub_かsub_かを確認する。移行ツールはwsub_の照会と既定の即時解約に対応しますが、変更には対応しません。sub_はそのまま Stripe へ転送します。 metadataやイベント名が enum や定数で組み立てられている——静的スキャンでは列挙しきれないため、タグが実際に付いているか手動で確認する。
スキャナーは正規表現とファイルコンテキストを使い、Java AST を解析しません。出力は棚卸しであり、受け入れの判断材料にはなりません。
ROUTED_LIKELY は特に注意が必要です——明確なレッドラインが見つからなかったことだけを意味します。作成時、契約設定を取得できる場合はアダプターが通貨を事前確認し、取得できない場合は Waffo の作成 API が検証します。支払い方法はマッピングによる事前チェックのみで、契約に含まれるかどうかは同じく Waffo の作成 API が検証します。動的に組み立てられるパラメーターも実行時にしか分かりません。最終的な判断は Sandbox 検証 で行ってください。ユーザーの二重支払いを防ぐためフォールバックしないケース
onUnsupported の設定にかかわらず、次のケースは Stripe へフォールバックしません。
冪等競合またはネットワーク上の不明状態。 Waffo がすでにサブスクリプションを作成している可能性があるため、同じ冪等キーで照会します。既存サブスクリプションが見つかれば成功として返します。確認できない場合は自動フォールバックに対応しないため、照会して最終状態を確認してください。
Waffo の明確な拒否。 同じキーで照会し、サブスクリプションが存在しないことを確認できた場合だけ理由コードに従ってフォールバックします。不明な結果では自動フォールバックに対応しません。
目的は、ユーザーへの二重請求を防ぐことです。
バージョン互換性とリリース検証
stripe-java は provided 依存関係で、バージョンはプロジェクト側が決めます。
各
waffo-java-stripe リリース前に、固定した 14 個の stripe-java 安定版で決定論的テストと Sandbox 回帰を実行します。変更履歴は CHANGELOG を参照してください。
関連リソース
- Stripe 移行ツール — 機能と適用判断
- Webhook 署名検証 — Waffo 通知の署名方式
- 冪等性 — Waffo の冪等キー設計
- エラーコード — Waffo エラーコードの意味を確認
- GitHub リポジトリ — ソースコードと変更履歴