Collect an account to build data-powered products

Register for Financial Connections after your account is approved for live-mode access.

Server-side

This integration requires endpoints on your server that communicate with the Stripe API. Use the 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 Stripe Android SDK is open source and fully documented.

To install the SDK, add financial-connections to the dependencies block of your app/build.gradle file:

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

  // Financial Connections Android SDK
  implementation("com.stripe:financial-connections:21.20.2")
}

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.

Before displaying the Financial Connections flow, your page should include a Connect Financial Account button to present the Stripe’s UI.

Initialize a FinancialConnectionsSheet instance inside onCreate of your checkout Activity, passing a method to handle the result.

import com.stripe.android.financialconnections.FinancialConnectionsSheet

class MyHostActivity : AppCompatActivity() {
  lateinit var financialConnectionsSheet: FinancialConnectionsSheet

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    financialConnectionsSheet = FinancialConnectionsSheet.create(this, ::onFinancialConnectionsSheetResult)
  }

  fun onFinancialConnectionsSheetResult(result: FinancialConnectionsSheetResult) {
    // implemented in the next steps
  }
}

Next, fetch the FinancialConnectionsSession client secret, and publishable key from the endpoint you created in the previous step. Set these fields using the FinancialConnectionsSheet.Configuration and store the others for use when you present the FinancialConnectionsSheet.

import com.stripe.android.financialconnections.FinancialConnectionsSheet
// Add the following lines to build.gradle to use this example's networking library:
//   implementation 'com.github.kittinunf.fuel:fuel:2.3.1'
//   implementation 'com.github.kittinunf.fuel:fuel-json:2.3.1'
import com.github.kittinunf.fuel.httpPost
import com.github.kittinunf.fuel.json.responseJson
import com.github.kittinunf.result.Result

class MyHostActivity : AppCompatActivity() {
  lateinit var financialConnectionsSheet: FinancialConnectionsSheet
  lateinit var clientSecret: String
  lateinit var publishableKey: String

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    financialConnectionsSheet = FinancialConnectionsSheet.create(this, ::onFinancialConnectionsSheetResult)
    "Your backend endpoint/connections-sheet".httpPost().responseJson { _, _, result ->
      if (result is Result.Success) {
        val responseJson = result.get().obj()
        clientSecret = responseJson.getString("financialConnectionsSessionClientSecret")
        publishableKey = responseJson.getString("publishableKey")
      }
    }
  }

  fun onFinancialConnectionsSheetResult(result: FinancialConnectionsSheetResult) {
    // implemented in the next steps
  }
}

When the customer taps your Connect Financial Account button, call FinancialConnectionsSheet#present to present the Financial Connections Sheet. After the customer completes the connection, the sheet closes. The FinancialConnectionsSheetResultCallback that you declared in the preceding step is called with FinancialConnectionsSheetResult.

// ...
class MyHostActivity : AppCompatActivity() {
  lateinit var financialConnectionsSheet: FinancialConnectionsSheet
  lateinit var clientSecret: String
  lateinit var publishableKey: String
  // ...
  fun presentFinancialConnectionsSheet() {
    financialConnectionsSheet.present(
      configuration = FinancialConnectionsSheet.Configuration(
        financialConnectionsSessionClientSecret = clientSecret,
        publishableKey = publishableKey
      )
    )
  }

  fun onFinancialConnectionsSheetResult(result: FinancialConnectionsSheetResult) {
    when(result) {
      is FinancialConnectionsSheetResult.Canceled -> {
        print("Canceled")
      }
      is FinancialConnectionsSheetResult.Failed -> {
        print("Failed")
        print("${result.error}")
      }
      is FinancialConnectionsSheetResult.Completed -> {
        // Display for example, a list of accounts.
        val accountInfos = result.financialConnectionsSession.accounts.data
          .map { "${it.institutionName} ${it.last4}" }
        print("Completed with ${accountInfos.joinToString("\n")} accounts")
      }
    }
  }
}

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.