@stripe/stripe-react-native 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.42.0 - 2025-02-25
+
+**Features**
+
+- Added ability to pass an `onEvent` listener to Financial Connections methods via a `params` argument. This includes the following methods, both when used directly or via `useStripe` or `useFinancialConnectionsSheet`:
+  - `collectBankAccountForPayment`
+  - `collectBankAccountForSetup`
+  - `collectBankAccountToken`
+  - `collectFinancialConnectionsAccounts`
+- Added ability to pass `metadata` to `PaymentMethod.ConfirmParams` and `PaymentMethod.CreateParams`
+
+## 0.41.0 - 2024-12-19
+
+**Fixes**
+
+- Updated `stripe-ios` to 24.2.\*
+
 ## 0.40.0 - 2024-11-19
 
 **Breaking changes**
@@ -24,8 +41,8 @@
 
 **Fixes**
 
-* Updated `stripe-ios` to 23.30.\*
-* Updated `stripe-android` to 20.52.\*
+- Updated `stripe-ios` to 23.30.\*
+- Updated `stripe-android` to 20.52.\*
 
 ## 0.38.6 - 2024-09-04
 

package/README.md

@@ -5,6 +5,9 @@
 
 The Stripe React Native SDK allows you to build delightful payment experiences in your native Android and iOS apps using React Native. We provide powerful and customizable UI screens and elements that can be used out-of-the-box to collect your users' payment details.
 
+> [!WARNING]
+> Until we support React Native's [New Architecture](https://reactnative.dev/blog/2024/10/23/the-new-architecture-is-here), if you are using React Native 0.76 or higher, we recommend [opting out](https://reactnative.dev/blog/2024/10/23/the-new-architecture-is-here#opt-out) of it.
+
 ## Getting started
 
 Get started with our [📚 integration guides](https://stripe.com/docs/payments/accept-a-payment?platform=react-native) and [example project](./CONTRIBUTING.md#running-the-example-app), or [📘 browse the SDK reference](https://stripe.dev/stripe-react-native).

package/android/.project

@@ -14,4 +14,15 @@
 	<natures>
 		<nature>org.eclipse.buildship.core.gradleprojectnature</nature>
 	</natures>
+	<filteredResources>
+		<filter>
+			<id>1740526494888</id>
+			<name></name>
+			<type>30</type>
+			<matcher>
+				<id>org.eclipse.core.resources.regexFilterMatcher</id>
+				<arguments>node_modules|\.git|__CREATED_BY_JAVA_LANGUAGE_SERVER__</arguments>
+			</matcher>
+		</filter>
+	</filteredResources>
 </projectDescription>

package/android/.settings/org.eclipse.buildship.core.prefs

@@ -1,11 +1,11 @@
-arguments=
+arguments=--init-script /var/folders/qg/5wmspvx516145k8z2q01c8_m0000gn/T/db3b08fc4a9ef609cb16b96b200fa13e563f396e9bb1ed0905fdab7bc3bc513b.gradle --init-script /var/folders/qg/5wmspvx516145k8z2q01c8_m0000gn/T/52cde0cfcf3e28b8b7510e992210d9614505e0911af0c190bd590d7158574963.gradle
 auto.sync=false
 build.scans.enabled=false
-connection.gradle.distribution=GRADLE_DISTRIBUTION(VERSION(6.0))
+connection.gradle.distribution=GRADLE_DISTRIBUTION(VERSION(8.9))
 connection.project.dir=
 eclipse.preferences.version=1
 gradle.user.home=
-java.home=/Library/Java/JavaVirtualMachines/jdk1.8.0_144.jdk/Contents/Home
+java.home=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
 jvm.arguments=
 offline.mode=false
 override.workspace.settings=true

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

@@ -7,6 +7,7 @@ import android.view.ViewGroup
 import android.widget.FrameLayout
 import androidx.appcompat.app.AppCompatActivity
 import androidx.fragment.app.Fragment
+import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
 import com.reactnativestripesdk.utils.*
@@ -14,6 +15,7 @@ import com.reactnativestripesdk.utils.createError
 import com.reactnativestripesdk.utils.createResult
 import com.reactnativestripesdk.utils.mapFromPaymentIntentResult
 import com.reactnativestripesdk.utils.mapFromSetupIntentResult
+import com.stripe.android.financialconnections.FinancialConnections
 import com.stripe.android.model.PaymentIntent
 import com.stripe.android.model.SetupIntent
 import com.stripe.android.model.StripeIntent
@@ -32,6 +34,18 @@ class CollectBankAccountLauncherFragment(
 ) : Fragment() {
   private lateinit var collectBankAccountLauncher: CollectBankAccountLauncher
 
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+
+    val stripeSdkModule: StripeSdkModule? = context.getNativeModule(StripeSdkModule::class.java)
+    if (stripeSdkModule != null && stripeSdkModule.eventListenerCount > 0) {
+      FinancialConnections.setEventListener { event ->
+        val params = mapFromFinancialConnectionsEvent(event)
+        stripeSdkModule.sendEvent(context, "onFinancialConnectionsEvent", params)
+      }
+    }
+  }
+
   override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?,
                             savedInstanceState: Bundle?): View {
     collectBankAccountLauncher = createBankAccountLauncher()
@@ -63,6 +77,13 @@ class CollectBankAccountLauncherFragment(
     }
   }
 
+  override fun onDestroy() {
+    super.onDestroy()
+
+    // Remove any event listener that might be set
+    FinancialConnections.clearEventListener()
+  }
+
   private fun createBankAccountLauncher(): CollectBankAccountLauncher {
     return CollectBankAccountLauncher.create(this) { result ->
       when (result) {

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

@@ -12,6 +12,7 @@ import com.reactnativestripesdk.utils.*
 import com.reactnativestripesdk.utils.createError
 import com.reactnativestripesdk.utils.createMissingActivityError
 import com.reactnativestripesdk.utils.mapFromToken
+import com.stripe.android.financialconnections.FinancialConnections
 import com.stripe.android.financialconnections.FinancialConnectionsSheet
 import com.stripe.android.financialconnections.FinancialConnectionsSheetForTokenResult
 import com.stripe.android.financialconnections.FinancialConnectionsSheetResult
@@ -27,6 +28,18 @@ class FinancialConnectionsSheetFragment : Fragment() {
   private lateinit var configuration: FinancialConnectionsSheet.Configuration
   private lateinit var mode: Mode
 
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+
+    val stripeSdkModule: StripeSdkModule? = context.getNativeModule(StripeSdkModule::class.java)
+    if (stripeSdkModule != null && stripeSdkModule.eventListenerCount > 0) {
+      FinancialConnections.setEventListener { event ->
+        val params = mapFromFinancialConnectionsEvent(event)
+        stripeSdkModule.sendEvent(context, "onFinancialConnectionsEvent", params)
+      }
+    }
+  }
+
   override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?,
                             savedInstanceState: Bundle?): View {
     return FrameLayout(requireActivity()).also {
@@ -55,6 +68,13 @@ class FinancialConnectionsSheetFragment : Fragment() {
     }
   }
 
+  override fun onDestroy() {
+    super.onDestroy()
+
+    // Remove any event listener that might be set
+    FinancialConnections.clearEventListener()
+  }
+
   private fun onFinancialConnectionsSheetForTokenResult(result: FinancialConnectionsSheetForTokenResult) {
     when(result) {
       is FinancialConnectionsSheetForTokenResult.Canceled -> {

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

@@ -3,6 +3,7 @@ package com.reactnativestripesdk
 import com.facebook.react.bridge.ReadableMap
 import com.reactnativestripesdk.utils.*
 import com.reactnativestripesdk.utils.mapToBillingDetails
+import com.reactnativestripesdk.utils.mapToMetadata
 import com.reactnativestripesdk.utils.mapToUSBankAccountHolderType
 import com.reactnativestripesdk.utils.mapToUSBankAccountType
 import com.stripe.android.model.*
@@ -13,7 +14,12 @@ class PaymentMethodCreateParamsFactory(
   private val cardFieldView: CardFieldView?,
   private val cardFormView: CardFormView?,
 ) {
-  private val billingDetailsParams = mapToBillingDetails(getMapOrNull(paymentMethodData, "billingDetails"), cardFieldView?.cardAddress ?: cardFormView?.cardAddress)
+  private val billingDetailsParams = mapToBillingDetails(
+    getMapOrNull(paymentMethodData, "billingDetails"),
+    cardFieldView?.cardAddress ?: cardFormView?.cardAddress
+  )
+  private val metadataParams: Map<String, String>? =
+    mapToMetadata(getMapOrNull(paymentMethodData, "metadata"))
 
   @Throws(PaymentMethodCreateParamsException::class)
   fun createPaymentMethodParams(paymentMethodType: PaymentMethod.Type): PaymentMethodCreateParams {
@@ -53,7 +59,11 @@ class PaymentMethodCreateParamsFactory(
     val bankName = getValOr(paymentMethodData, "bankName", null)
 
     val idealParams = PaymentMethodCreateParams.Ideal(bankName)
-    return PaymentMethodCreateParams.create(ideal = idealParams, billingDetails = billingDetailsParams)
+    return PaymentMethodCreateParams.create(
+      ideal = idealParams,
+      billingDetails = billingDetailsParams,
+      metadata = metadataParams
+    )
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
@@ -69,14 +79,18 @@ class PaymentMethodCreateParamsFactory(
 
     return PaymentMethodCreateParams.create(
       PaymentMethodCreateParams.Sofort(country = country),
-      billingDetailsParams
+      billingDetailsParams,
+      metadata = metadataParams
     )
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createBancontactParams(): PaymentMethodCreateParams {
     billingDetailsParams?.let {
-      return PaymentMethodCreateParams.createBancontact(it)
+      return PaymentMethodCreateParams.createBancontact(
+        billingDetails = it,
+        metadata = metadataParams
+      )
     }
 
     throw PaymentMethodCreateParamsException("You must provide billing details")
@@ -91,7 +105,8 @@ class PaymentMethodCreateParamsFactory(
 
       return PaymentMethodCreateParams.create(
         sepaDebit = PaymentMethodCreateParams.SepaDebit(iban),
-        billingDetails = it
+        billingDetails = it,
+        metadata = metadataParams
       )
     }
 
@@ -101,7 +116,10 @@ class PaymentMethodCreateParamsFactory(
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createOXXOParams(): PaymentMethodCreateParams {
     billingDetailsParams?.let {
-      return PaymentMethodCreateParams.createOxxo(it)
+      return PaymentMethodCreateParams.createOxxo(
+        billingDetails = it,
+        metadata = metadataParams
+      )
     }
 
     throw PaymentMethodCreateParamsException("You must provide billing details")
@@ -110,7 +128,10 @@ class PaymentMethodCreateParamsFactory(
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createGiropayParams(): PaymentMethodCreateParams {
     billingDetailsParams?.let {
-      return PaymentMethodCreateParams.createGiropay(it)
+      return PaymentMethodCreateParams.createGiropay(
+        billingDetails = it,
+        metadata = metadataParams
+      )
     }
 
     throw PaymentMethodCreateParamsException("You must provide billing details")
@@ -119,7 +140,10 @@ class PaymentMethodCreateParamsFactory(
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createEPSParams(): PaymentMethodCreateParams {
     billingDetailsParams?.let {
-      return PaymentMethodCreateParams.createEps(it)
+      return PaymentMethodCreateParams.createEps(
+        billingDetails = it,
+        metadata = metadataParams
+      )
     }
 
     throw PaymentMethodCreateParamsException("You must provide billing details")
@@ -134,7 +158,10 @@ class PaymentMethodCreateParamsFactory(
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createP24Params(): PaymentMethodCreateParams {
     billingDetailsParams?.let {
-      return PaymentMethodCreateParams.createP24(it)
+      return PaymentMethodCreateParams.createP24(
+        billingDetails = it,
+        metadata = metadataParams
+      )
     }
 
     throw PaymentMethodCreateParamsException("You must provide billing details")
@@ -144,14 +171,18 @@ class PaymentMethodCreateParamsFactory(
   private fun createFpxParams(): PaymentMethodCreateParams {
     val bank = getBooleanOrFalse(paymentMethodData, "testOfflineBank").let { "test_offline_bank" }
     return PaymentMethodCreateParams.create(
-      PaymentMethodCreateParams.Fpx(bank)
+      PaymentMethodCreateParams.Fpx(bank),
+      metadata = metadataParams
     )
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createAfterpayClearpayParams(): PaymentMethodCreateParams {
     billingDetailsParams?.let {
-      return PaymentMethodCreateParams.createAfterpayClearpay(it)
+      return PaymentMethodCreateParams.createAfterpayClearpay(
+        billingDetails = it,
+        metadata = metadataParams
+      )
     }
 
     throw PaymentMethodCreateParamsException("You must provide billing details")
@@ -178,7 +209,8 @@ class PaymentMethodCreateParamsFactory(
         bsbNumber = bsbNumber,
         accountNumber = accountNumber
       ),
-      billingDetails = billingDetails
+      billingDetails = billingDetails,
+      metadata = metadataParams
     )
   }
 
@@ -191,35 +223,57 @@ class PaymentMethodCreateParamsFactory(
       throw PaymentMethodCreateParamsException("Klarna requires that you provide the following billing details: email, country")
     }
 
-    return PaymentMethodCreateParams.createKlarna(billingDetailsParams)
+    return PaymentMethodCreateParams.createKlarna(
+      billingDetails = billingDetailsParams,
+      metadata = metadataParams
+    )
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createPayPalParams(): PaymentMethodCreateParams {
-    return PaymentMethodCreateParams.createPayPal(null)
+    return PaymentMethodCreateParams.createPayPal(
+      metadata = metadataParams
+    )
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createAffirmParams(): PaymentMethodCreateParams {
-    return PaymentMethodCreateParams.createAffirm(billingDetailsParams)
+    return PaymentMethodCreateParams.createAffirm(
+      billingDetails = billingDetailsParams,
+      metadata = metadataParams
+    )
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createCashAppParams(): PaymentMethodCreateParams {
-    return PaymentMethodCreateParams.createCashAppPay(billingDetailsParams)
+    return PaymentMethodCreateParams.createCashAppPay(
+      billingDetails = billingDetailsParams,
+      metadata = metadataParams
+    )
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
   private fun createRevolutPayParams(): PaymentMethodCreateParams {
-    return PaymentMethodCreateParams.createRevolutPay(billingDetailsParams)
+    return PaymentMethodCreateParams.createRevolutPay(
+      billingDetails = billingDetailsParams,
+      metadata = metadataParams
+    )
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
-  fun createParams(clientSecret: String, paymentMethodType: PaymentMethod.Type?, isPaymentIntent: Boolean): ConfirmStripeIntentParams {
+  fun createParams(
+    clientSecret: String,
+    paymentMethodType: PaymentMethod.Type?,
+    isPaymentIntent: Boolean
+  ): ConfirmStripeIntentParams {
     try {
       return when (paymentMethodType) {
         PaymentMethod.Type.Card -> createCardStripeIntentParams(clientSecret, isPaymentIntent)
-        PaymentMethod.Type.USBankAccount -> createUSBankAccountStripeIntentParams(clientSecret, isPaymentIntent)
+        PaymentMethod.Type.USBankAccount -> createUSBankAccountStripeIntentParams(
+          clientSecret,
+          isPaymentIntent
+        )
+
         PaymentMethod.Type.Affirm -> createAffirmStripeIntentParams(clientSecret, isPaymentIntent)
         PaymentMethod.Type.Ideal,
         PaymentMethod.Type.Alipay,
@@ -245,7 +299,12 @@ class PaymentMethodCreateParamsFactory(
               .createWithPaymentMethodCreateParams(
                 paymentMethodCreateParams = params,
                 clientSecret = clientSecret,
-                setupFutureUsage = mapToPaymentIntentFutureUsage(getValOr(options, "setupFutureUsage")),
+                setupFutureUsage = mapToPaymentIntentFutureUsage(
+                  getValOr(
+                    options,
+                    "setupFutureUsage"
+                  )
+                ),
                 mandateData = buildMandateDataParams()
               )
           } else {
@@ -256,6 +315,7 @@ class PaymentMethodCreateParamsFactory(
             )
           }
         }
+
         null -> ConfirmPaymentIntentParams.create(clientSecret)
         else -> {
           throw Exception("This paymentMethodType is not supported yet")
@@ -283,7 +343,10 @@ class PaymentMethodCreateParamsFactory(
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
-  private fun createCardStripeIntentParams(clientSecret: String, isPaymentIntent: Boolean): ConfirmStripeIntentParams {
+  private fun createCardStripeIntentParams(
+    clientSecret: String,
+    isPaymentIntent: Boolean
+  ): ConfirmStripeIntentParams {
     val paymentMethodId = getValOr(paymentMethodData, "paymentMethodId", null)
     val setupFutureUsage = mapToPaymentIntentFutureUsage(getValOr(options, "setupFutureUsage"))
 
@@ -298,11 +361,13 @@ class PaymentMethodCreateParamsFactory(
             paymentMethodId,
             paymentMethodOptions = paymentMethodOptionParams,
             clientSecret = clientSecret,
-            setupFutureUsage = setupFutureUsage)
+            setupFutureUsage = setupFutureUsage
+          )
         else
           ConfirmSetupIntentParams.create(
             paymentMethodId,
-            clientSecret)
+            clientSecret
+          )
         )
     } else {
       val paymentMethodCreateParams = createCardPaymentMethodParams()
@@ -312,7 +377,8 @@ class PaymentMethodCreateParamsFactory(
             .createWithPaymentMethodCreateParams(
               paymentMethodCreateParams,
               clientSecret,
-              setupFutureUsage = setupFutureUsage)
+              setupFutureUsage = setupFutureUsage
+            )
         else
           ConfirmSetupIntentParams
             .create(paymentMethodCreateParams, clientSecret)
@@ -321,7 +387,10 @@ class PaymentMethodCreateParamsFactory(
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
-  private fun createUSBankAccountStripeIntentParams(clientSecret: String, isPaymentIntent: Boolean): ConfirmStripeIntentParams {
+  private fun createUSBankAccountStripeIntentParams(
+    clientSecret: String,
+    isPaymentIntent: Boolean
+  ): ConfirmStripeIntentParams {
     // If payment method data is supplied, assume they are passing in the bank details manually
     paymentMethodData?.let {
       if (billingDetailsParams?.name.isNullOrBlank()) {
@@ -344,7 +413,8 @@ class PaymentMethodCreateParamsFactory(
       return if (isPaymentIntent) {
         ConfirmPaymentIntentParams.create(
           clientSecret = clientSecret,
-          paymentMethodType = PaymentMethod.Type.USBankAccount
+          paymentMethodType = PaymentMethod.Type.USBankAccount,
+
         )
       } else {
         ConfirmSetupIntentParams.create(
@@ -356,7 +426,10 @@ class PaymentMethodCreateParamsFactory(
   }
 
   @Throws(PaymentMethodCreateParamsException::class)
-  private fun createAffirmStripeIntentParams(clientSecret: String, isPaymentIntent: Boolean): ConfirmStripeIntentParams {
+  private fun createAffirmStripeIntentParams(
+    clientSecret: String,
+    isPaymentIntent: Boolean
+  ): ConfirmStripeIntentParams {
     if (!isPaymentIntent) {
       throw PaymentMethodCreateParamsException("Affirm is not yet supported through SetupIntents.")
     }
@@ -368,7 +441,7 @@ class PaymentMethodCreateParamsFactory(
         paymentMethodCreateParams = params,
         clientSecret = clientSecret,
         setupFutureUsage = mapToPaymentIntentFutureUsage(getValOr(options, "setupFutureUsage")),
-        mandateData = buildMandateDataParams()
+        mandateData = buildMandateDataParams(),
       )
   }
 
@@ -390,18 +463,22 @@ class PaymentMethodCreateParamsFactory(
         getValOr(
           params,
           "accountType",
-          null)),
+          null
+        )
+      ),
       mapToUSBankAccountHolderType(
         getValOr(
           params,
           "accountHolderType",
-          null))
+          null
+        )
+      )
     )
 
     return PaymentMethodCreateParams.Companion.create(
       usBankAccount,
       billingDetailsParams,
-      null
+      metadataParams
     )
   }
 
@@ -409,10 +486,12 @@ class PaymentMethodCreateParamsFactory(
     getMapOrNull(paymentMethodData, "mandateData")?.let { mandateData ->
       getMapOrNull(mandateData, "customerAcceptance")?.let { customerAcceptance ->
         getMapOrNull(customerAcceptance, "online")?.let { onlineParams ->
-          return MandateDataParams(MandateDataParams.Type.Online(
-            ipAddress = getValOr(onlineParams, "ipAddress", "") ?: "",
-            userAgent = getValOr(onlineParams, "userAgent", "") ?: "",
-          ))
+          return MandateDataParams(
+            MandateDataParams.Type.Online(
+              ipAddress = getValOr(onlineParams, "ipAddress", "") ?: "",
+              userAgent = getValOr(onlineParams, "userAgent", "") ?: "",
+            )
+          )
         }
       }
     }

package/android/src/main/java/com/reactnativestripesdk/utils/Mappers.kt

@@ -4,6 +4,7 @@ import android.annotation.SuppressLint
 import android.os.Bundle
 import android.util.Log
 import com.facebook.react.bridge.*
+import com.stripe.android.financialconnections.analytics.FinancialConnectionsEvent
 import com.stripe.android.PaymentAuthConfig
 import com.stripe.android.model.*
 import com.stripe.android.model.StripeIntent.NextActionType
@@ -598,6 +599,10 @@ internal fun mapToBillingDetails(billingDetails: ReadableMap?, cardAddress: Addr
   return paymentMethodBillingDetailsBuilder.build()
 }
 
+internal fun mapToMetadata(metadata: ReadableMap?): Map<String, String>? {
+  return metadata?.toHashMap()?.mapValues { it.value.toString() }
+}
+
 internal fun mapToShippingDetails(shippingDetails: ReadableMap?): ConfirmPaymentIntentParams.Shipping? {
   if (shippingDetails == null) {
     return null
@@ -957,3 +962,48 @@ internal fun mapToPreferredNetworks(networksAsInts: ArrayList<Int>?): List<CardB
     intToCardBrand[it]
   }
 }
+
+internal fun mapFromFinancialConnectionsEvent(event: FinancialConnectionsEvent): WritableMap {
+  return Arguments.createMap().apply {
+    putString("name", event.name.value)
+    putMap("metadata", event.metadata.toMap().toReadableMap())
+  }
+}
+
+private fun List<Any?>.toWritableArray(): WritableArray {
+  val writableArray = Arguments.createArray()
+
+  forEach { value ->
+    when (value) {
+      null -> writableArray.pushNull()
+      is Boolean -> writableArray.pushBoolean(value)
+      is Int -> writableArray.pushInt(value)
+      is Double -> writableArray.pushDouble(value)
+      is String -> writableArray.pushString(value)
+      is Map<*, *> -> writableArray.pushMap((value as Map<String, Any?>).toReadableMap())
+      is List<*> -> writableArray.pushArray((value as List<Any?>).toWritableArray())
+      else -> writableArray.pushString(value.toString())
+    }
+  }
+
+  return writableArray
+}
+
+private fun Map<String, Any?>.toReadableMap(): ReadableMap {
+  val writableMap = Arguments.createMap()
+
+  forEach { (key, value) ->
+    when (value) {
+      null -> writableMap.putNull(key)
+      is Boolean -> writableMap.putBoolean(key, value)
+      is Int -> writableMap.putInt(key, value)
+      is Double -> writableMap.putDouble(key, value)
+      is String -> writableMap.putString(key, value)
+      is Map<*, *> -> writableMap.putMap(key, (value as Map<String, Any?>).toReadableMap())
+      is List<*> -> writableMap.putArray(key, (value as List<Any?>).toWritableArray())
+      else -> writableMap.putString(key, value.toString())
+    }
+  }
+
+  return writableMap
+}

package/ios/FinancialConnections.swift

@@ -14,10 +14,16 @@ class FinancialConnections {
     internal static func present(
         withClientSecret: String,
         returnURL: String? = nil,
+        onEvent: ((FinancialConnectionsEvent) -> Void)? = nil,
         resolve: @escaping RCTPromiseResolveBlock
     ) -> Void {
         DispatchQueue.main.async {
-            FinancialConnectionsSheet(financialConnectionsSessionClientSecret: withClientSecret, returnURL: returnURL).present(
+            let financialConnectionsSheet = FinancialConnectionsSheet(
+              financialConnectionsSessionClientSecret: withClientSecret,
+              returnURL: returnURL
+            )
+            financialConnectionsSheet.onEvent = onEvent
+            financialConnectionsSheet.present(
               from: findViewControllerPresenter(from: UIApplication.shared.delegate?.window??.rootViewController ?? UIViewController()),
               completion: { result in
                   switch result {
@@ -35,10 +41,16 @@ class FinancialConnections {
     internal static func presentForToken(
         withClientSecret: String,
         returnURL: String? = nil,
+        onEvent: ((FinancialConnectionsEvent) -> Void)? = nil,
         resolve: @escaping RCTPromiseResolveBlock
     ) -> Void {
         DispatchQueue.main.async {
-            FinancialConnectionsSheet(financialConnectionsSessionClientSecret: withClientSecret, returnURL: returnURL).presentForToken(
+            let financialConnectionsSheet = FinancialConnectionsSheet(
+              financialConnectionsSessionClientSecret: withClientSecret,
+              returnURL: returnURL
+            )
+            financialConnectionsSheet.onEvent = onEvent
+            financialConnectionsSheet.presentForToken(
               from: findViewControllerPresenter(from: UIApplication.shared.delegate?.window??.rootViewController ?? UIViewController()),
               completion: { result in
                   switch result {

package/ios/Mappers.swift

@@ -1050,4 +1050,27 @@ class Mappers {
             return nil
         }
     }
+
+    class func financialConnectionsEventToMap(_ event: FinancialConnectionsEvent) -> [String: Any] {
+      var metadata: [String: Any] = [:]
+
+      if let manualEntry = event.metadata.manualEntry {
+        metadata["manualEntry"] = manualEntry
+      }
+
+      if let institutionName = event.metadata.institutionName {
+        metadata["institutionName"] = institutionName
+      }
+
+      if let errorCode = event.metadata.errorCode {
+        metadata["errorCode"] = errorCode.rawValue
+      }
+
+      let mappedEvent: [String: Any] = [
+        "name": event.name.rawValue,
+        "metadata": metadata
+      ]
+
+      return mappedEvent
+    }
 }