Deprecate PaymentSheet Constructors and FlowController.create()

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### PaymentSheet
 * [ADDED][10935](https://github.com/stripe/stripe-android/pull/10935) Add `formInsetValues` method to `PaymentSheet.Appearance.Builder`.
+* [DEPRECATED][10833](https://github.com/stripe/stripe-android/pull/10833) Deprecated PaymentSheet/FlowController constructors, create methods, and Compose remember functions in favor of new Builder pattern APIs.
 
 ## 21.17.0 - 2025-06-09
 

MIGRATING.md

@@ -1,5 +1,15 @@
 # Migration Guide
 
+## Migrating from versions < 21.18.0
+- Changes to `PaymentSheet`:
+  * The constructors have been deprecated and will be removed in a future release. Use `PaymentSheet.Builder` instead.
+- Changes to `PaymentSheet.FlowController`:
+  * `FlowController.create()` has been deprecated and will be removed in a future release. Use `FlowController.Builder` instead.
+- Changes to `rememberPaymentSheet`:
+  * The functions have been deprecated and will be removed in a future release. Use `PaymentSheet.Builder` with `remember` instead.
+- Changes to `rememberPaymentSheetFlowController`:
+  * The functions have been deprecated and will be removed in a future release. Use `FlowController.Builder` with `remember` instead.
+
 ## Migrating from versions < 21.0.0
 - Basic Integration has been removed. [Please use Mobile Payment Element instead](https://docs.stripe.com/payments/mobile/migrating-to-mobile-payment-element-from-basic-integration).
 - Card image verification has been removed. [Please use card OCR instead](https://github.com/stripe/stripe-android/tree/master/stripecardscan#credit-card-ocr).

paymentsheet/src/androidTest/java/com/stripe/android/paymentsheet/FlowControllerTest.kt

@@ -338,6 +338,7 @@ internal class FlowControllerTest {
             scenario.onActivity {
                 PaymentConfiguration.init(it, "pk_test_123")
 
+                @Suppress("Deprecation")
                 val unsynchronizedController = PaymentSheet.FlowController.create(
                     activity = it,
                     paymentOptionCallback = { paymentOption ->
@@ -404,6 +405,7 @@ internal class FlowControllerTest {
         scenario.moveToState(Lifecycle.State.CREATED)
         scenario.onActivity {
             PaymentConfiguration.init(it, "pk_test_123")
+            @Suppress("Deprecation")
             flowController = PaymentSheet.FlowController.create(
                 activity = it,
                 paymentOptionCallback = {

paymentsheet/src/androidTest/java/com/stripe/android/paymentsheet/PaymentSheetBillingConfigurationTest.kt

@@ -12,6 +12,7 @@ import com.stripe.android.networktesting.RequestMatchers.method
 import com.stripe.android.networktesting.RequestMatchers.not
 import com.stripe.android.networktesting.RequestMatchers.path
 import com.stripe.android.networktesting.testBodyFromFile
+import com.stripe.android.paymentsheet.PaymentSheet.Builder
 import com.stripe.android.paymentsheet.utils.IntegrationType
 import com.stripe.android.paymentsheet.utils.PaymentSheetLayoutType
 import com.stripe.android.paymentsheet.utils.PaymentSheetLayoutTypeProvider
@@ -53,10 +54,10 @@ internal class PaymentSheetBillingConfigurationTest {
         lateinit var paymentSheet: PaymentSheet
         scenario.onActivity {
             PaymentConfiguration.init(it, "pk_test_123")
-            paymentSheet = PaymentSheet(it) { result ->
+            paymentSheet = Builder { result ->
                 assertThat(result).isInstanceOf(PaymentSheetResult.Completed::class.java)
                 countDownLatch.countDown()
-            }
+            }.build(it)
         }
         scenario.moveToState(Lifecycle.State.RESUMED)
         scenario.onActivity {
@@ -130,10 +131,10 @@ internal class PaymentSheetBillingConfigurationTest {
         lateinit var paymentSheet: PaymentSheet
         scenario.onActivity {
             PaymentConfiguration.init(it, "pk_test_123")
-            paymentSheet = PaymentSheet(it) { result ->
+            paymentSheet = Builder { result ->
                 assertThat(result).isInstanceOf(PaymentSheetResult.Completed::class.java)
                 countDownLatch.countDown()
-            }
+            }.build(it)
         }
         scenario.moveToState(Lifecycle.State.RESUMED)
         scenario.onActivity {

paymentsheet/src/main/java/com/stripe/android/paymentsheet/FlowControllerCompose.kt

@@ -21,6 +21,14 @@ import java.util.UUID
  * @param paymentResultCallback Called when a [PaymentSheetResult] is available.
  */
 @Composable
+@Deprecated(
+    message = "This will be removed in a future release. Use FlowController.Builder instead.",
+    replaceWith = ReplaceWith(
+        "remember(paymentOptionCallback, paymentResultCallback) { " +
+            "PaymentSheet.FlowController.Builder(paymentResultCallback, paymentOptionCallback) " +
+            "}.build()"
+    )
+)
 fun rememberPaymentSheetFlowController(
     paymentOptionCallback: PaymentOptionCallback,
     paymentResultCallback: PaymentSheetResultCallback,
@@ -49,6 +57,15 @@ fun rememberPaymentSheetFlowController(
  * @param paymentResultCallback Called when a [PaymentSheetResult] is available.
  */
 @Composable
+@Deprecated(
+    message = "This will be removed in a future release. Use FlowController.Builder instead.",
+    replaceWith = ReplaceWith(
+        "remember(createIntentCallback, paymentOptionCallback, paymentResultCallback) { " +
+            "PaymentSheet.FlowController.Builder(paymentResultCallback, paymentOptionCallback)" +
+            ".createIntentCallback(createIntentCallback) " +
+            "}.build()"
+    )
+)
 fun rememberPaymentSheetFlowController(
     createIntentCallback: CreateIntentCallback,
     paymentOptionCallback: PaymentOptionCallback,
@@ -82,6 +99,21 @@ fun rememberPaymentSheetFlowController(
  * @param paymentResultCallback Called when a [PaymentSheetResult] is available.
  */
 @Composable
+@Deprecated(
+    message = "This will be removed in a future release. Use FlowController.Builder instead.",
+    replaceWith = ReplaceWith(
+        "remember(" +
+            "createIntentCallback, " +
+            "externalPaymentMethodConfirmHandler, " +
+            "paymentOptionCallback, " +
+            "paymentResultCallback" +
+            ") { " +
+            "PaymentSheet.FlowController.Builder(paymentResultCallback, paymentOptionCallback)" +
+            ".createIntentCallback(createIntentCallback)" +
+            ".externalPaymentMethodConfirmHandler(externalPaymentMethodConfirmHandler) " +
+            "}.build()"
+    )
+)
 fun rememberPaymentSheetFlowController(
     createIntentCallback: CreateIntentCallback? = null,
     externalPaymentMethodConfirmHandler: ExternalPaymentMethodConfirmHandler,

paymentsheet/src/main/java/com/stripe/android/paymentsheet/PaymentSheet.kt

@@ -58,6 +58,10 @@ class PaymentSheet internal constructor(
      * @param activity The Activity that is presenting [PaymentSheet].
      * @param callback Called with the result of the payment after [PaymentSheet] is dismissed.
      */
+    @Deprecated(
+        message = "This will be removed in a future release.",
+        replaceWith = ReplaceWith("PaymentSheet.Builder(callback).build(activity)")
+    )
     constructor(
         activity: ComponentActivity,
         callback: PaymentSheetResultCallback
@@ -73,6 +77,14 @@ class PaymentSheet internal constructor(
      * @param externalPaymentMethodConfirmHandler Called when a user confirms payment with an external payment method.
      * @param callback Called with the result of the payment after [PaymentSheet] is dismissed.
      */
+    @Deprecated(
+        message = "This will be removed in a future release.",
+        replaceWith = ReplaceWith(
+            "PaymentSheet.Builder(callback)" +
+                ".externalPaymentMethodConfirmHandler(externalPaymentMethodConfirmHandler)" +
+                ".build(activity)"
+        )
+    )
     constructor(
         activity: ComponentActivity,
         externalPaymentMethodConfirmHandler: ExternalPaymentMethodConfirmHandler,
@@ -96,6 +108,14 @@ class PaymentSheet internal constructor(
      * @param paymentResultCallback Called with the result of the payment or setup after
      * [PaymentSheet] is dismissed.
      */
+    @Deprecated(
+        message = "This will be removed in a future release.",
+        replaceWith = ReplaceWith(
+            "PaymentSheet.Builder(paymentResultCallback)" +
+                ".createIntentCallback(createIntentCallback)" +
+                ".build(activity)"
+        )
+    )
     constructor(
         activity: ComponentActivity,
         createIntentCallback: CreateIntentCallback,
@@ -121,6 +141,15 @@ class PaymentSheet internal constructor(
      * @param paymentResultCallback Called with the result of the payment or setup after
      * [PaymentSheet] is dismissed.
      */
+    @Deprecated(
+        message = "This will be removed in a future release.",
+        replaceWith = ReplaceWith(
+            "PaymentSheet.Builder(paymentResultCallback)" +
+                ".createIntentCallback(createIntentCallback)" +
+                ".externalPaymentMethodConfirmHandler(externalPaymentMethodConfirmHandler)" +
+                ".build(activity)"
+        )
+    )
     constructor(
         activity: ComponentActivity,
         createIntentCallback: CreateIntentCallback,
@@ -143,6 +172,10 @@ class PaymentSheet internal constructor(
      * @param fragment the Fragment that is presenting the payment sheet.
      * @param callback called with the result of the payment after the payment sheet is dismissed.
      */
+    @Deprecated(
+        message = "This will be removed in a future release.",
+        replaceWith = ReplaceWith("PaymentSheet.Builder(callback).build(fragment)")
+    )
     constructor(
         fragment: Fragment,
         callback: PaymentSheetResultCallback
@@ -158,6 +191,14 @@ class PaymentSheet internal constructor(
      * @param externalPaymentMethodConfirmHandler Called when a user confirms payment with an external payment method.
      * @param callback called with the result of the payment after the payment sheet is dismissed.
      */
+    @Deprecated(
+        message = "This will be removed in a future release.",
+        replaceWith = ReplaceWith(
+            "PaymentSheet.Builder(callback)" +
+                ".externalPaymentMethodConfirmHandler(externalPaymentMethodConfirmHandler)" +
+                ".build(fragment)"
+        )
+    )
     constructor(
         fragment: Fragment,
         externalPaymentMethodConfirmHandler: ExternalPaymentMethodConfirmHandler,
@@ -181,6 +222,14 @@ class PaymentSheet internal constructor(
      * @param paymentResultCallback Called with the result of the payment or setup after
      * [PaymentSheet] is dismissed.
      */
+    @Deprecated(
+        message = "This will be removed in a future release.",
+        replaceWith = ReplaceWith(
+            "PaymentSheet.Builder(paymentResultCallback)" +
+                ".createIntentCallback(createIntentCallback)" +
+                ".build(fragment)"
+        )
+    )
     constructor(
         fragment: Fragment,
         createIntentCallback: CreateIntentCallback,
@@ -206,6 +255,15 @@ class PaymentSheet internal constructor(
      * @param paymentResultCallback Called with the result of the payment or setup after
      * [PaymentSheet] is dismissed.
      */
+    @Deprecated(
+        message = "This will be removed in a future release.",
+        replaceWith = ReplaceWith(
+            "PaymentSheet.Builder(paymentResultCallback)" +
+                ".createIntentCallback(createIntentCallback)" +
+                ".externalPaymentMethodConfirmHandler(externalPaymentMethodConfirmHandler)" +
+                ".build(fragment)"
+        )
+    )
     constructor(
         fragment: Fragment,
         createIntentCallback: CreateIntentCallback,
@@ -2648,6 +2706,12 @@ class PaymentSheet internal constructor(
              * [PaymentSheet] is dismissed.
              */
             @JvmStatic
+            @Deprecated(
+                message = "This will be removed in a future release.",
+                replaceWith = ReplaceWith(
+                    "FlowController.Builder(paymentResultCallback, paymentOptionCallback).build(activity)"
+                )
+            )
             fun create(
                 activity: ComponentActivity,
                 paymentOptionCallback: PaymentOptionCallback,
@@ -2675,6 +2739,14 @@ class PaymentSheet internal constructor(
              * [PaymentSheet] is dismissed.
              */
             @JvmStatic
+            @Deprecated(
+                message = "This will be removed in a future release.",
+                replaceWith = ReplaceWith(
+                    "FlowController.Builder(paymentResultCallback, paymentOptionCallback)" +
+                        ".externalPaymentMethodConfirmHandler(externalPaymentMethodConfirmHandler)" +
+                        ".build(activity)"
+                )
+            )
             fun create(
                 activity: ComponentActivity,
                 externalPaymentMethodConfirmHandler: ExternalPaymentMethodConfirmHandler,
@@ -2705,6 +2777,14 @@ class PaymentSheet internal constructor(
              * [PaymentSheet] is dismissed.
              */
             @JvmStatic
+            @Deprecated(
+                message = "This will be removed in a future release.",
+                replaceWith = ReplaceWith(
+                    "FlowController.Builder(paymentResultCallback, paymentOptionCallback)" +
+                        ".createIntentCallback(createIntentCallback)" +
+                        ".build(activity)"
+                )
+            )
             fun create(
                 activity: ComponentActivity,
                 paymentOptionCallback: PaymentOptionCallback,
@@ -2739,6 +2819,15 @@ class PaymentSheet internal constructor(
              * [PaymentSheet] is dismissed.
              */
             @JvmStatic
+            @Deprecated(
+                message = "This will be removed in a future release.",
+                replaceWith = ReplaceWith(
+                    "FlowController.Builder(paymentResultCallback, paymentOptionCallback)" +
+                        ".createIntentCallback(createIntentCallback)" +
+                        ".externalPaymentMethodConfirmHandler(externalPaymentMethodConfirmHandler)" +
+                        ".build(activity)"
+                )
+            )
             fun create(
                 activity: ComponentActivity,
                 paymentOptionCallback: PaymentOptionCallback,
@@ -2768,6 +2857,12 @@ class PaymentSheet internal constructor(
              * @param paymentResultCallback called when a [PaymentSheetResult] is available.
              */
             @JvmStatic
+            @Deprecated(
+                message = "This will be removed in a future release.",
+                replaceWith = ReplaceWith(
+                    "FlowController.Builder(paymentResultCallback, paymentOptionCallback).build(fragment)"
+                )
+            )
             fun create(
                 fragment: Fragment,
                 paymentOptionCallback: PaymentOptionCallback,
@@ -2793,6 +2888,14 @@ class PaymentSheet internal constructor(
              * @param paymentResultCallback called when a [PaymentSheetResult] is available.
              */
             @JvmStatic
+            @Deprecated(
+                message = "This will be removed in a future release.",
+                replaceWith = ReplaceWith(
+                    "FlowController.Builder(paymentResultCallback, paymentOptionCallback)" +
+                        ".externalPaymentMethodConfirmHandler(externalPaymentMethodConfirmHandler)" +
+                        ".build(fragment)"
+                )
+            )
             fun create(
                 fragment: Fragment,
                 externalPaymentMethodConfirmHandler: ExternalPaymentMethodConfirmHandler,
@@ -2823,6 +2926,14 @@ class PaymentSheet internal constructor(
              * [PaymentSheet] is dismissed.
              */
             @JvmStatic
+            @Deprecated(
+                message = "This will be removed in a future release.",
+                replaceWith = ReplaceWith(
+                    "FlowController.Builder(paymentResultCallback, paymentOptionCallback)" +
+                        ".createIntentCallback(createIntentCallback)" +
+                        ".build(fragment)"
+                )
+            )
             fun create(
                 fragment: Fragment,
                 paymentOptionCallback: PaymentOptionCallback,
@@ -2857,6 +2968,15 @@ class PaymentSheet internal constructor(
              * [PaymentSheet] is dismissed.
              */
             @JvmStatic
+            @Deprecated(
+                message = "This will be removed in a future release.",
+                replaceWith = ReplaceWith(
+                    "FlowController.Builder(paymentResultCallback, paymentOptionCallback)" +
+                        ".createIntentCallback(createIntentCallback)" +
+                        ".externalPaymentMethodConfirmHandler(externalPaymentMethodConfirmHandler)" +
+                        ".build(fragment)"
+                )
+            )
             fun create(
                 fragment: Fragment,
                 paymentOptionCallback: PaymentOptionCallback,