Skip to main content
このガイドでは、Stripe 移行ツールを Java プロジェクトへ導入し、有効期限が近づいた Stripe サブスクリプションを Waffo へ移行する手順を説明します。 Stripe 移行ツールを読み、この移行方法がプロジェクトに合うことを確認してから進めてください。

前提条件

  • Waffo とサブスクリプション契約を締結し、Sandbox の API キー、RSA 鍵ペア、加盟店番号を取得している。
  • stripe-java が 24.11.0 以上である。
  • Waffo 通知を受け取る公開 HTTPS エンドポイントがある。
  • 使用する通貨が契約範囲に含まれている。paymethodconfig/inquiry で確認できる。

ステップ 1:依存関係を追加

プロジェクトで使用中の 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 のシークレットキーを保持しません。
アダプターは Waffo 向けリクエストへ X-Waffo-Client: waffo-stripe-java/<version> ヘッダーを自動で設定します。独自にトランスポート層を包んでこの値を作る必要はありません。
移行中は FAIL_LOUD を使用してください。 既定の FALLBACK はルーティングできない作成リクエストを Stripe へ転送するため、移行漏れを見つけにくくなります。問題をすべて確認した後、運用時の安全策として FALLBACK に戻してください。
タイムアウトやプロキシを設定した既存の 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 と同時に設定しないでください。この組み合わせはマッピングエラーとして扱われます。
冪等キーは 32 文字以内にしてください。呼び出し前に生成して永続化し、再試行でも同じキーを使用します。アダプターはこのキーを Waffo の subscriptionRequest として使い、作成結果の確認とサブスクリプションの重複防止を行います。32 文字を超える業務注文 ID を直接渡さないでください。現行バージョンは長いキーを不可逆な 32 文字のダイジェストへ変換するため、Webhook から元の値を復元できません。既存の注文 ID が長い場合は、32 文字以内の安定した関連付けキーを別途生成し、注文 ID との対応を永続化してください。stripe-java が自動生成する冪等キーに依存しないでください。アダプターは Stripe の通信層が自動キーを生成する前にリクエストをインターセプトするため、そのキーは Waffo の subscriptionRequest になりません。RequestOptions でキーを明示的に渡さない場合、次回の呼び出しで永続化して再利用することもできません。
作成後の id は次のようにルーティングされます。
  • Session.idwcs_ で始まり、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 通知を変換

設定した notifyUrlhandle(...) を呼び出します。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:初期リリース対象外のプラン変更です。
  • 終端状態ではない返金通知。
checkout.session.completed で提供処理を行うプロジェクトは改修が必要です。 このイベントは変換されません。サブスクリプションの有効化と権限付与を customer.subscription.createdinvoice.paid に移し、ビジネスレベルの冪等性で二重付与を防いでください。
従来の translate(body, signature) はソース互換性のため残っていますが、戻り値は Event だけで、上記の確認レスポンスを取得できません。新規連携では handle(...) を使用してください。

ステップ 5:即時解約を組み込む

移行ツールは Stripe の既定の解約呼び出しを使った Waffo サブスクリプションの即時解約に対応します。期間終了時解約、指定時刻での解約、サブスクリプション更新は再現しません。 まず両者の違いを整理します。 既定の解約は Waffo subscription/cancel を呼び出し、同じサブスクリプションを照会して解約済みの最終状態を確認します。結果が不明な場合、移行ツールは同じ wsub_… の照会だけで結果を回復し、Stripe へ転送しません。handoffAt を待っている間に解約すると、予定された初回請求は発生しません。
invoice_now=trueprorate=true など追加の請求セマンティクスを持つ解約はエラーになります。Waffo には Stripe の期間終了時解約に相当する機能もありません。cancel_at_period_end、指定時刻での解約、解約の取り消し、または Subscription.update("wsub_…") に依存するフローは Stripe に残してください。

連携チェックリスト

依存関係と設定

  • Maven Central から依存バージョンを解決できることを確認した。
  • stripe-java が 24.11.0 以上である。
  • WaffoStripe.client(...) と Sandbox 設定を組み込んだ。

コード変更

  • 対象リクエストに metadata.source=waffo があり、冪等キーを呼び出し前に永続化した。
  • Webhook エンドポイントが handle(...) を使い、SDK が生成したレスポンス本文を返す。
  • PAYMENT_NOTIFICATION をサブスクリプション課金として別に処理する。
  • 提供処理を checkout.session.completed から customer.subscription.createdinvoice.paid へ移した。
  • wsub_ サブスクリプションを照会して既定の即時解約を実行でき、期間終了時解約などの未対応機能に依存していない。
  • 同じ handoffAt を使って Stripe の更新を停止し、Waffo billing_cycle_anchor を設定している。

検証

  • FAIL_LOUD が示したすべてのフォールバックを確認した。
  • プロジェクト自身のビルドとテストが成功した。
  • Sandbox のエンドツーエンドフローを完了した。

Sandbox 検証

検証はプロジェクト自身の HTTP エンドポイントから実行してください。アダプター内部のテストだけでは不十分です。

設定リファレンス

連携では同名でパッケージが異なる 2 つの WaffoConfig を使用します。

1. ルーティング設定 com.waffo.stripe.config.WaffoConfig

2. OnUnsupported の値

このパラメーターが及ぶ範囲は限られています。 制御するのは、送信前または明確な拒否を受けた時点でルーティング不可と判断できる 5 つのケースだけです——レッドラインに該当、Waffo による明確な拒否、支払い方法が未対応、フィールド変換の失敗、Waffo クライアント未設定。冪等競合とネットワーク上の不明状態の扱いには影響しません。それらは独立した処理に委ねられます(ユーザーの二重支払いを防ぐためフォールバックしないケースを参照)。

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 へ送られます。
移行中は onUnsupported=FAIL_LOUD を維持してください。「Stripe にフォールバック」のケースも例外として表面化するため、1 件ずつ確認できます。すべて確認した後で、本番環境の安全策として FALLBACK に切り替えます(設定リファレンスを参照)。

該当箇所を事前にスキャン

AI 移行スキルのスキャナーは Stripe 呼び出しを次のように分類します。 スキャナーが判定できず、手動で追う必要があるのは主に次の点です。
  • パラメーターが別ファイル、ファクトリーメソッド、独自ラッパーで組み立てられている——create に実際に渡る値まで追跡し、上の表と 1 つずつ照合する。
  • 変更 / 解約の対象 id の由来が不明——業務フローを辿って wsub_sub_ かを確認する。移行ツールは wsub_ の照会と既定の即時解約に対応しますが、変更には対応しません。sub_ はそのまま Stripe へ転送します。
  • metadata やイベント名が enum や定数で組み立てられている——静的スキャンでは列挙しきれないため、タグが実際に付いているか手動で確認する。
候補となるサブスクリプション作成と SubscriptionItem または SubscriptionSchedule の呼び出しが同じプロジェクトにある場合、まず各呼び出しがどの作成フローに属するか確認してください。複数 item、proration、またはスケジュールフェーズに依存するフローは、全体を Stripe に残します。所有関係を確認できるまで、候補の作成リクエストに source=waffo を追加しないでください。
スキャナーは正規表現とファイルコンテキストを使い、Java AST を解析しません。出力は棚卸しであり、受け入れの判断材料にはなりません。 ROUTED_LIKELY は特に注意が必要です——明確なレッドラインが見つからなかったことだけを意味します。作成時、契約設定を取得できる場合はアダプターが通貨を事前確認し、取得できない場合は Waffo の作成 API が検証します。支払い方法はマッピングによる事前チェックのみで、契約に含まれるかどうかは同じく Waffo の作成 API が検証します。動的に組み立てられるパラメーターも実行時にしか分かりません。最終的な判断は Sandbox 検証 で行ってください。

ユーザーの二重支払いを防ぐためフォールバックしないケース

onUnsupported の設定にかかわらず、次のケースは Stripe へフォールバックしません。 冪等競合またはネットワーク上の不明状態。 Waffo がすでにサブスクリプションを作成している可能性があるため、同じ冪等キーで照会します。既存サブスクリプションが見つかれば成功として返します。確認できない場合は自動フォールバックに対応しないため、照会して最終状態を確認してください。 Waffo の明確な拒否。 同じキーで照会し、サブスクリプションが存在しないことを確認できた場合だけ理由コードに従ってフォールバックします。不明な結果では自動フォールバックに対応しません。 目的は、ユーザーへの二重請求を防ぐことです。

バージョン互換性とリリース検証

stripe-java は provided 依存関係で、バージョンはプロジェクト側が決めます。 waffo-java-stripe リリース前に、固定した 14 個の stripe-java 安定版で決定論的テストと Sandbox 回帰を実行します。変更履歴は CHANGELOG を参照してください。

関連リソース