Collect an account to build data-powered products

Server-side

This integration requires endpoints on your server that talk to the Stripe API. Use our official libraries for access to the Stripe API from your server:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Client-side

The React Native SDK is open source and fully documented. Internally, it uses the native iOS and Android SDKs. To install Stripe’s React Native SDK, run one of the following commands in your project’s directory (depending on which package manager you use):

yarn add @stripe/stripe-react-native

Next, install some other necessary dependencies:

• For iOS, navigate to the ios directory and run pod install to ensure that you also install the required native dependencies.
• For Android, there are no more dependencies to install.

Stripe initialization

To initialize Stripe in your React Native app, either wrap your payment screen with the StripeProvider component, or use the initStripe initialization method. Only the API publishable key in publishableKey is required. The following example shows how to initialize Stripe using the StripeProvider component.

import { useState, useEffect } from 'react';
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}

Create a Customer object when users create an account with your business. By providing an email address, Financial Connections can optimize the authentication flow by dynamically showing a streamlined user interface, for returning Link users.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}}

Before you can retrieve data from a user’s bank account with Financial Connections, your user must authenticate their account with the authentication flow.

Your user begins the authentication flow when they want to connect their account to your site or application. Insert a button or link on your site or in your application, which allows a user to link their account—for example, your button might say “Link your bank account”.

Create a Financial Connections Session by posting to /v1/financial_connections/sessions:

curl https://api.stripe.com/v1/financial_connections/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "account_holder[type]"=customer \
  -d "account_holder[customer]"=
{{CUSTOMER_ID}} \
  -d "permissions[]"=balances \
  -d "permissions[]"=ownership \
  -d "permissions[]"=payment_method \
  -d "permissions[]"=transactions

1. Set account_holder[customer] to the Customer id.
2. Set the data permissions parameter to include the data required to fulfill your use case.
3. (Optional) set the prefetch parameter for retrieving the data on account creation.

The permissions parameter controls which account data you can access. You must request at least one permission. When completing the authentication flow, your user can see the data you’ve requested access to, and provide their consent to share it.

Consider the data required to fulfill your use case and request permission to access only the data you need. Requesting permissions that go well beyond your application’s scope might erode your users’ trust in how you use their data. For example, if you’re building a personal financial management application or a lending product, you might request transactions data. If you’re mitigating fraud such as account takeovers, you might want to request ownership details.

After your user authenticates their account, you can expand data permissions only by creating a new Financial Connections Session and specifying a new value for the permissions parameter. Your user must complete the authentication flow again, where they’ll see the additional data you’ve requested permission to access, and provide consent to share their data.

The optional prefetch parameter controls which data you retrieve immediately after the user connects their account. Use this option if you know you always want a certain type of data. It removes the need to make an extra API call to initiate a data refresh.

To preserve the option to accept ACH Direct Debit payments, request the payment_method permission.

Import the collectFinancialConnectionsAccounts function from Stripe’s React Native SDK.

import {collectFinancialConnectionsAccounts} from '@stripe/stripe-react-native';

Use collectFinancialConnectionsAccounts to collect the bank account by passing in the client_secret from above, and then handle the result appropriately:

// Assume you have a <Button /> to collect payout accounts, whose onPress is handleCollectPress
const handleCollectPress = async () => {
  // Fetch the clientSecret you created above and pass it to collectFinancialConnectionsAccounts
  const {session, error} = await collectFinancialConnectionsAccounts(
    clientSecret,
  );

  if (error) {
    Alert.alert(`Error code: ${error.code}`, error.message);
  } else {
    Alert.alert('Success');
    console.log(
      'Successfully obtained session: ',
      JSON.stringify(session, null, 2),
    );
  }
};

collectFinancialConnectionsAccounts returns a Promise. When your user completes the modal flow, the Promise resolves with one of the following:

• A session, representing the completed Financial Connections Session, if the user can successfully link their account. This session includes an accounts array that contains the list of connected accounts.
• An error if the Session fails or is canceled.

By default your connected accounts can only add account types like a checking or savings account in the authentication flow because Stripe can only facilitate payouts to an ACH-enabled account.

When a customer exits your app (for example to authenticate in Safari or their banking app), provide a way for them to automatically return to your app. Many payment method types require a return URL. If you don’t provide one, we can’t present payment methods that require a return URL to your users, even if you’ve enabled them.

To provide a return URL:

1. Register a custom URL. Universal links aren’t supported.
2. Configure your custom URL.
3. Set up your root component to forward the URL to the Stripe SDK as shown below.

import { useEffect, useCallback } from 'react';
import { Linking } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';

export default function MyApp() {
  const { handleURLCallback } = useStripe();

  const handleDeepLink = useCallback(
    async (url: string | null) => {
      if (url) {
        const stripeHandled = await handleURLCallback(url);
        if (stripeHandled) {
          // This was a Stripe URL - you can return or add extra handling here as you see fit
        } else {
          // This was NOT a Stripe URL – handle as you normally would
        }
      }
    },
    [handleURLCallback]
  );

  useEffect(() => {
    const getUrlAsync = async () => {
      const initialUrl = await Linking.getInitialURL();
      handleDeepLink(initialUrl);
    };

    getUrlAsync();

    const deepLinkListener = Linking.addEventListener(
      'url',
      (event: { url: string }) => {
        handleDeepLink(event.url);
      }
    );

    return () => deepLinkListener.remove();
  }, [handleDeepLink]);

  return (
    <View>
      <AwesomeAppComponent />
    </View>
  );
}

For more information on native URL schemes, refer to the Android and iOS docs.

After your user has successfully completed the authentication flow, access or refresh the account data you’ve specified in the permissions parameter of the Financial Connections Session.

To protect the privacy of your user’s data, account data accessible to you is limited to the data you’ve specified in the permissions parameter.

Follow the guides for balances, ownership and transactions to start retrieving account data.