@stripe/stripe-react-native 0.50.0 → 0.50.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## 0.50.2 - 2025-08-06
+
+**Changes**
+- Renamed `RowStyle.FlatWithChevron` to `RowStyle.FlatWithDisclosure` and updated related interfaces (`ChevronConfig` → `DisclosureConfig`).
+- Updated `stripe-ios` to 24.19.0
+- Updated `stripe-android` to 21.22.+
+- Added `successBackgroundColor` and `successTextColor` properties to `PrimaryButtonColorConfig` for customizing the primary button appearance in success states.
+
+**Fixes**
+- Fixed missing `onCustomPaymentMethodConfirmHandlerCallback` in old architecture codegen patch. This resolves pod install failures when using React Native 0.74+ with old architecture and custom payment methods.
+- Fixes an issue where saved payment methods weren't auto selected when using `EmbeddedPaymentElement` on Android.
+
+## 0.50.1 - 2025-07-22
+
+**Fixes**
+- Fixed embedded payment element color support to accept both single color strings and light/dark color objects for `ThemedColor` properties (separatorColor, selectedColor, unselectedColor, checkmark color, chevron color).
+- Fixed Android crash when providing partial `billingDetailsCollectionConfiguration` objects. Now gracefully handles missing fields like `attachDefaultsToPaymentMethod` by using safe accessor methods with default values.
+- Fixed Android Kotlin compilation errors where nullable `ReadableMap?` was passed to functions expecting non-nullable `ReadableMap`. Added null checks in `EmbeddedPaymentElementViewManager` and `AddToWalletButtonManager`. [#1988](https://github.com/stripe/stripe-react-native/issues/1988)
+
 ## 0.50.0 - 2025-07-17
 
 **Features**

package/CLAUDE.md

@@ -0,0 +1,148 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Building and Linting
+- `yarn typescript` - Type-check TypeScript files
+- `yarn lint` - Lint code with ESLint
+- `yarn lint --fix` - Fix linting issues automatically
+- `yarn test` - Run Jest unit tests
+- `yarn prepare` - Build the library (runs `bob build && husky`)
+
+### Development Setup
+- `yarn bootstrap` - Setup project by installing dependencies and CocoaPods
+- `yarn bootstrap-no-pods` - Setup without installing CocoaPods
+- `yarn pods` - Install CocoaPods for iOS (example app)
+- `yarn update-pods` - Update specific Stripe pod dependencies
+
+### Example App Development Workflow
+1. **Setup**: `yarn bootstrap`
+2. **Run Example App** (requires 2 terminals):
+   - Terminal 1: `yarn example start`
+   - Terminal 2: `yarn example ios` OR `yarn example android`
+
+The example app uses a pre-configured demo backend, so no server setup is required.
+
+### Example App Commands
+- `yarn example start` - Start Metro server
+- `yarn run-example-ios` - Run iOS example app on iPhone 16 simulator
+- `yarn run-example-android` - Run Android example app
+- `yarn run-example-ios:release` - Build and run iOS app in release mode
+- `yarn run-example-android:release` - Build and run Android app in release mode
+
+### Testing
+- `yarn test:e2e:ios` - Run all iOS E2E tests using Maestro
+- `yarn test:e2e:android` - Run all Android E2E tests using Maestro
+- `yarn test-ios ./path/to/test.yml` - Run single iOS E2E test
+- `yarn test-android ./path/to/test.yml` - Run single Android E2E test
+- `yarn test:unit:ios` - Run iOS native unit tests via Xcode
+- `yarn test:unit:android` - Run Android unit tests
+
+### Documentation
+- `yarn docs` - Generate API documentation using TypeDoc
+
+### Commit Convention
+Follow [conventional commits](https://www.conventionalcommits.org/en):
+- `fix:` - Bug fixes
+- `feat:` - New features
+- `refactor:` - Code refactoring
+- `docs:` - Documentation changes
+- `test:` - Test additions/updates
+- `chore:` - Tooling changes
+
+## Architecture Overview
+
+This is the official Stripe React Native SDK, providing payment processing capabilities for mobile apps.
+
+### Key Directories
+
+- **`src/`** - Main TypeScript source code
+  - `components/` - React Native components (CardField, PaymentSheet, etc.)
+  - `hooks/` - React hooks for payment functionality
+  - `types/` - TypeScript type definitions
+  - `specs/` - Native module specifications for code generation
+  - `functions.ts` - Core payment functions
+  - `index.tsx` - Main exports
+
+- **`ios/`** - Native iOS implementation in Swift/Objective-C
+  - Uses Stripe iOS SDK (~24.16.1)
+  - Supports both Old and New Architecture (Fabric)
+  - Test files in `ios/Tests/`
+
+- **`android/`** - Native Android implementation in Kotlin/Java
+  - Uses Stripe Android SDK
+  - Gradle build configuration
+
+- **`example/`** - Example React Native app demonstrating SDK usage
+  - Contains test server in `server/` directory
+  - Configured for both iOS and Android development
+
+- **`e2e-tests/`** - End-to-end tests using Maestro framework
+  - Platform-specific tests in `ios-only/` and `android-only/`
+  - Tests payment flows, UI components, and integrations
+
+### Code Generation
+
+The SDK uses React Native's TurboModules/Fabric for native communication:
+- Specs defined in `src/specs/` generate native interfaces
+- Both Old and New Architecture supported
+- Special patch for Old Architecture compatibility in `patches/old-arch-codegen-fix.patch`
+
+### Build System
+
+- **React Native Builder Bob** - Builds CommonJS, ES modules, and TypeScript declarations
+- **CocoaPods** - iOS dependency management
+- **Gradle** - Android build system
+- **Expo Plugin** - `src/plugin/withStripe.ts` for Expo integration
+
+### Key Components
+
+- **StripeProvider** - Context provider for SDK initialization
+- **PaymentSheet** - Pre-built payment UI
+- **CardField/CardForm** - Card input components
+- **PlatformPayButton** - Apple Pay/Google Pay integration
+- **CustomerSheet** - Customer payment method management
+- **AddressSheet** - Address collection component
+
+### Testing Strategy
+
+- **Jest** - Unit tests for TypeScript code
+- **Maestro** - E2E testing framework for mobile flows
+- **Native Tests** - iOS XCTest and Android instrumentation tests
+- Mock implementation provided in `jest/mock.js`
+
+### Platform-Specific Notes
+
+- **iOS**: Requires Xcode 14.1+, iOS 13+ deployment target
+- **Android**: Requires API 21+, compileSdkVersion 34, Kotlin 2.x
+- **React Native**: Compatible with 0.78+, TypeScript 5.7+
+- **Expo**: Supported via plugin configuration
+
+### Development File Locations
+
+- **iOS Native**: Open `example/ios/StripeSdkExample.xcworkspace` in Xcode
+  - Source files: `Pods > Development Pods > stripe-react-native`
+- **Android Native**: Open `example/android` in Android Studio
+  - Source files: `reactnativestripesdk` under `Android`
+- **TypeScript**: Edit files in `src/` and `example/`
+
+### GitHub Issue Management
+- `GH_HOST=github.com gh issue list --repo stripe/stripe-react-native --limit 20` - List recent issues
+- `GH_HOST=github.com gh issue view <issue_number> --repo stripe/stripe-react-native` - View specific issue
+- `GH_HOST=github.com gh issue view <issue_number> --repo stripe/stripe-react-native --comments` - View issue with comments
+- `GH_HOST=github.com gh issue list --repo stripe/stripe-react-native --state all --search "keyword" --limit 30` - Search ALL issues (open/closed) by keyword
+- `GH_HOST=github.com gh issue create --repo stripe/stripe-react-native` - Create new issue
+- `GH_HOST=github.com gh issue edit <issue_number> --repo stripe/stripe-react-native` - Edit issue
+- `GH_HOST=github.com gh pr create --repo stripe/stripe-react-native` - Create pull request
+- Always use `--state all` when searching to include closed/resolved issues
+- Always check GitHub issues for similar problems before investigating user reports
+- Use GitHub CLI to distinguish between SDK bugs vs integration issues
+
+### Filing PRs
+When using the GitHub `gh` command, ALWAYS set `GH_HOST=github.com`. For example: `GH_HOST=github.com gh pr create --title [...]`
+
+### Old Architecture Compatibility
+
+The SDK maintains compatibility with React Native's Old Architecture via `patches/old-arch-codegen-fix.patch`. This patch converts EventEmitter properties to callback functions for code generation compatibility with RN ≥ 0.74.

package/android/gradle.properties

@@ -3,4 +3,4 @@ StripeSdk_compileSdkVersion=30
 StripeSdk_targetSdkVersion=28
 StripeSdk_minSdkVersion=21
 # Keep StripeSdk_stripeVersion in sync with https://github.com/stripe/stripe-identity-react-native/blob/main/android/gradle.properties
-StripeSdk_stripeVersion=21.19.+
+StripeSdk_stripeVersion=21.22.+

package/android/src/main/java/com/reactnativestripesdk/EmbeddedPaymentElementViewManager.kt

@@ -17,6 +17,7 @@ import com.reactnativestripesdk.PaymentSheetFragment.Companion.buildGooglePayCon
 import com.reactnativestripesdk.addresssheet.AddressSheetView
 import com.reactnativestripesdk.utils.PaymentSheetAppearanceException
 import com.reactnativestripesdk.utils.PaymentSheetException
+import com.reactnativestripesdk.utils.getBooleanOr
 import com.reactnativestripesdk.utils.mapToPreferredNetworks
 import com.reactnativestripesdk.utils.parseCustomPaymentMethods
 import com.reactnativestripesdk.utils.toBundleObject
@@ -54,10 +55,13 @@ class EmbeddedPaymentElementViewManager :
     view: EmbeddedPaymentElementView,
     cfg: Dynamic,
   ) {
-    val rowSelectionBehaviorType = parseRowSelectionBehavior(cfg.asMap())
+    val readableMap = cfg.asMap()
+    if (readableMap == null) return
+
+    val rowSelectionBehaviorType = parseRowSelectionBehavior(readableMap)
     view.rowSelectionBehaviorType.value = rowSelectionBehaviorType
 
-    val elementConfig = parseElementConfiguration(cfg.asMap(), view.context)
+    val elementConfig = parseElementConfiguration(readableMap, view.context)
     view.latestElementConfig = elementConfig
     // if intentConfig is already set, configure immediately:
     view.latestIntentConfig?.let { intentCfg ->
@@ -74,7 +78,9 @@ class EmbeddedPaymentElementViewManager :
     view: EmbeddedPaymentElementView,
     cfg: Dynamic,
   ) {
-    val intentConfig = parseIntentConfiguration(cfg.asMap())
+    val readableMap = cfg.asMap()
+    if (readableMap == null) return
+    val intentConfig = parseIntentConfiguration(readableMap)
     view.latestIntentConfig = intentConfig
     view.latestElementConfig?.let { elemCfg ->
       view.configure(elemCfg, intentConfig)
@@ -147,7 +153,7 @@ class EmbeddedPaymentElementViewManager :
         email = mapToCollectionMode(billingConfigParams?.getString("email")),
         address = mapToAddressCollectionMode(billingConfigParams?.getString("address")),
         attachDefaultsToPaymentMethod =
-          billingConfigParams?.getBoolean("attachDefaultsToPaymentMethod") ?: false,
+          billingConfigParams?.getBooleanOr("attachDefaultsToPaymentMethod", false) ?: false,
       )
     val allowsRemovalOfLastSavedPaymentMethod =
       if (map.hasKey("allowsRemovalOfLastSavedPaymentMethod")) {

package/android/src/main/java/com/reactnativestripesdk/PaymentSheetAppearance.kt

@@ -194,9 +194,9 @@ private fun buildPrimaryButton(
 
   return PaymentSheet.PrimaryButton(
     colorsLight =
-      buildPrimaryButtonColors(lightColorParams, PaymentSheet.PrimaryButtonColors.defaultLight),
+      buildPrimaryButtonColors(lightColorParams, PaymentSheet.PrimaryButtonColors.defaultLight, context),
     colorsDark =
-      buildPrimaryButtonColors(darkColorParams, PaymentSheet.PrimaryButtonColors.defaultDark),
+      buildPrimaryButtonColors(darkColorParams, PaymentSheet.PrimaryButtonColors.defaultDark, context),
     shape =
       PaymentSheet.PrimaryButtonShape(
         cornerRadiusDp =
@@ -217,6 +217,7 @@ private fun buildPrimaryButton(
 private fun buildPrimaryButtonColors(
   colorParams: Bundle,
   default: PaymentSheet.PrimaryButtonColors,
+  context: Context,
 ): PaymentSheet.PrimaryButtonColors =
   PaymentSheet.PrimaryButtonColors(
     background =
@@ -243,6 +244,20 @@ private fun buildPrimaryButtonColors(
         colorParams.getString(PaymentSheetAppearanceKeys.BORDER),
         default.border,
       ),
+    successBackgroundColor =
+      dynamicColorFromParams(
+        context,
+        colorParams,
+        PaymentSheetAppearanceKeys.SUCCESS_BACKGROUND,
+        default.successBackgroundColor,
+      ),
+    onSuccessBackgroundColor =
+      dynamicColorFromParams(
+        context,
+        colorParams,
+        PaymentSheetAppearanceKeys.SUCCESS_TEXT,
+        default.onSuccessBackgroundColor,
+      ),
   )
 
 @SuppressLint("RestrictedApi")
@@ -341,7 +356,7 @@ private fun buildEmbeddedAppearance(
         val checkmarkParams = getBundleOrNull(flatParams, PaymentSheetAppearanceKeys.CHECKMARK)
         val separatorInsetsParams = getBundleOrNull(flatParams, PaymentSheetAppearanceKeys.SEPARATOR_INSETS)
 
-        // Default separator insets specific to FlatWithCheckmark and FlatWithChevron
+        // Default separator insets specific to FlatWithCheckmark and FlatWithDisclosure
         val defaultSeparatorStartInsetDp = 0.0f
         val defaultSeparatorEndInsetDp = 0.0f
 
@@ -392,12 +407,12 @@ private fun buildEmbeddedAppearance(
           colorsDark = flatCheckmarkColors,
         )
       }
-      "flatWithChevron" -> {
+      "flatWithDisclosure" -> {
         val flatParams = getBundleOrNull(rowParams, PaymentSheetAppearanceKeys.FLAT)
-        val chevronParams = getBundleOrNull(flatParams, PaymentSheetAppearanceKeys.CHEVRON)
+        val disclosureParams = getBundleOrNull(flatParams, PaymentSheetAppearanceKeys.DISCLOSURE)
         val separatorInsetsParams = getBundleOrNull(flatParams, PaymentSheetAppearanceKeys.SEPARATOR_INSETS)
 
-        // Default separator insets specific to FlatWithCheckmark and FlatWithChevron
+        // Default separator insets specific to FlatWithCheckmark and FlatWithDisclosure
         val defaultSeparatorStartInsetDp = 0.0f
         val defaultSeparatorEndInsetDp = 0.0f
 
@@ -418,32 +433,33 @@ private fun buildEmbeddedAppearance(
             Color.GRAY,
           )
 
-        val parsedChevronColor =
+        val parsedDisclosureColor =
           dynamicColorFromParams(
             context,
-            chevronParams,
+            disclosureParams,
             PaymentSheetAppearanceKeys.COLOR,
             defaultColors.componentBorder, // Default to component border color like other elements
           )
 
         // Create the required Colors object
-        val flatChevronColors =
-          PaymentSheet.Appearance.Embedded.RowStyle.FlatWithChevron.Colors(
+        val flatDisclosureColors =
+          PaymentSheet.Appearance.Embedded.RowStyle.FlatWithDisclosure.Colors(
             separatorColor = parsedSeparatorColor,
-            chevronColor = parsedChevronColor,
+            disclosureColor = parsedDisclosureColor,
           )
 
-        PaymentSheet.Appearance.Embedded.RowStyle.FlatWithChevron(
-          separatorThicknessDp = separatorThickness,
-          startSeparatorInsetDp = startSeparatorInset,
-          endSeparatorInsetDp = endSeparatorInset,
-          topSeparatorEnabled = topEnabled,
-          bottomSeparatorEnabled = bottomEnabled,
-          additionalVerticalInsetsDp = additionalInsets,
-          horizontalInsetsDp = 0.0F, // We do not have an iOS equal for this API so it's not configurable in React Native
-          colorsLight = flatChevronColors,
-          colorsDark = flatChevronColors,
-        )
+        PaymentSheet.Appearance.Embedded.RowStyle.FlatWithDisclosure
+          .Builder()
+          .separatorThicknessDp(separatorThickness)
+          .startSeparatorInsetDp(startSeparatorInset)
+          .endSeparatorInsetDp(endSeparatorInset)
+          .topSeparatorEnabled(topEnabled)
+          .bottomSeparatorEnabled(bottomEnabled)
+          .additionalVerticalInsetsDp(additionalInsets)
+          .horizontalInsetsDp(0.0F) // We do not have an iOS equal for this API so it's not configurable in React Native
+          .colorsLight(flatDisclosureColors)
+          .colorsDark(flatDisclosureColors)
+          .build()
       }
       "floatingButton" -> {
         val floatingParams = getBundleOrNull(rowParams, PaymentSheetAppearanceKeys.FLOATING)
@@ -478,9 +494,11 @@ private fun buildFormInsets(insetParams: Bundle?): PaymentSheet.Insets {
 }
 
 /**
- * Pulls a light/dark hex‑string map out of [params],
- * chooses the right one based on the current UI mode,
- * and parses it (falling back to [defaultColor]).
+ * Parses a ThemedColor from [params] at [key]. Supports both:
+ * - Single hex string: "#RRGGBB"
+ * - Light/dark object: { "light": "#RRGGBB", "dark": "#RRGGBB" }
+ * For light/dark objects, chooses the appropriate color based on current UI mode.
+ * Falls back to [defaultColor] if no color is provided.
  */
 private fun dynamicColorFromParams(
   context: Context,
@@ -488,8 +506,12 @@ private fun dynamicColorFromParams(
   key: String,
   defaultColor: Int,
 ): Int {
-  // Expect a nested Bundle { "light": "#RRGGBB", "dark": "#RRGGBB" }
-  val colorBundle = params?.getBundle(key)
+  if (params == null) {
+    return defaultColor
+  }
+
+  // First check if it's a nested Bundle { "light": "#RRGGBB", "dark": "#RRGGBB" }
+  val colorBundle = params.getBundle(key)
   if (colorBundle != null) {
     val isDark =
       (
@@ -508,7 +530,12 @@ private fun dynamicColorFromParams(
     return colorFromHexOrDefault(hex, defaultColor)
   }
 
-  // no override bundle → just use default
+  // Check if it's a single color string
+  params.getString(key)?.let { colorString ->
+    return colorFromHexOrDefault(colorString, defaultColor)
+  }
+
+  // no override → just use default
   return defaultColor
 }
 
@@ -643,6 +670,8 @@ private class PaymentSheetAppearanceKeys {
     const val PRIMARY_BUTTON = "primaryButton"
     const val TEXT = "text"
     const val BORDER = "border"
+    const val SUCCESS_BACKGROUND = "successBackgroundColor"
+    const val SUCCESS_TEXT = "successTextColor"
 
     const val EMBEDDED_PAYMENT_ELEMENT = "embeddedPaymentElement"
     const val ROW = "row"
@@ -659,7 +688,7 @@ private class PaymentSheetAppearanceKeys {
     const val SELECTED_COLOR = "selectedColor"
     const val UNSELECTED_COLOR = "unselectedColor"
     const val CHECKMARK = "checkmark"
-    const val CHEVRON = "chevron"
+    const val DISCLOSURE = "disclosure"
     const val COLOR = "color"
     const val CHECKMARK_INSET = "inset"
 

package/android/src/main/java/com/reactnativestripesdk/PaymentSheetFragment.kt

@@ -218,7 +218,7 @@ class PaymentSheetFragment :
         email = mapToCollectionMode(billingConfigParams?.getString("email")),
         address = mapToAddressCollectionMode(billingConfigParams?.getString("address")),
         attachDefaultsToPaymentMethod =
-          billingConfigParams?.getBoolean("attachDefaultsToPaymentMethod") ?: false,
+          billingConfigParams?.getBoolean("attachDefaultsToPaymentMethod", false) ?: false,
       )
 
     var defaultBillingDetails: PaymentSheet.BillingDetails? = null
@@ -617,14 +617,13 @@ class PaymentSheetFragment :
     }
 
     @OptIn(PaymentMethodOptionsSetupFutureUsagePreview::class)
-    private fun buildIntentConfigurationMode(modeParams: Bundle): PaymentSheet.IntentConfiguration.Mode {
-      val currencyCode =
-        modeParams.getString("currencyCode")
-          ?: throw PaymentSheetException(
-            "You must provide a value to intentConfiguration.mode.currencyCode",
-          )
-
-      return if (modeParams.containsKey("amount")) {
+    private fun buildIntentConfigurationMode(modeParams: Bundle): PaymentSheet.IntentConfiguration.Mode =
+      if (modeParams.containsKey("amount")) {
+        val currencyCode =
+          modeParams.getString("currencyCode")
+            ?: throw PaymentSheetException(
+              "You must provide a value to intentConfiguration.mode.currencyCode",
+            )
         PaymentSheet.IntentConfiguration.Mode.Payment(
           amount = modeParams.getInt("amount").toLong(),
           currency = currencyCode,
@@ -639,11 +638,10 @@ class PaymentSheetFragment :
               "You must provide a value to intentConfiguration.mode.setupFutureUsage",
             )
         PaymentSheet.IntentConfiguration.Mode.Setup(
-          currency = currencyCode,
+          currency = modeParams.getString("currencyCode"),
           setupFutureUse = setupFutureUsage,
         )
       }
-    }
 
     @OptIn(ExperimentalCustomerSessionApi::class)
     @Throws(PaymentSheetException::class)

package/android/src/main/java/com/reactnativestripesdk/customersheet/CustomerSheetFragment.kt

@@ -309,7 +309,7 @@ class CustomerSheetFragment : StripeFragment() {
         phone = mapToCollectionMode(bundle.getString("phone")),
         email = mapToCollectionMode(bundle.getString("email")),
         address = mapToAddressCollectionMode(bundle.getString("address")),
-        attachDefaultsToPaymentMethod = bundle.getBoolean("attachDefaultsToPaymentMethod"),
+        attachDefaultsToPaymentMethod = bundle.getBoolean("attachDefaultsToPaymentMethod", false),
       )
 
     internal fun createCustomerAdapter(

package/android/src/main/java/com/reactnativestripesdk/pushprovisioning/AddToWalletButtonManager.kt

@@ -64,7 +64,9 @@ class AddToWalletButtonManager(
     view: AddToWalletButtonView,
     ephemeralKey: Dynamic,
   ) {
-    view.setEphemeralKey(ephemeralKey.asMap())
+    val map = ephemeralKey.asMap()
+    if (map == null) return
+    view.setEphemeralKey(map)
   }
 
   @ReactProp(name = "token")
@@ -72,7 +74,9 @@ class AddToWalletButtonManager(
     view: AddToWalletButtonView,
     token: Dynamic,
   ) {
-    view.setToken(token.asMap())
+    val map = token.asMap()
+    if (map == null) return
+    view.setToken(map)
   }
 
   @ReactProp(name = "iOSButtonStyle")