Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Session 

A Financial Connections Session is the secure way to programmatically launch the client-side Stripe.js modal that lets your users link their accounts.

Endpoints

The Session object 

Attributes

  • idstring

    Unique identifier for the object.

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • account_holdernullable object

    The account holder for whom accounts are collected in this session.

  • accountsobject

    The accounts that were collected as part of this Session.

  • client_secretstring

    A value that will be passed to the client to launch the authentication flow.

  • filtersnullable object

    Filters applied to this session that restrict the kinds of accounts to collect.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • permissionsarray of enums

    Permissions requested for accounts collected during this session.

    Possible enum values
    balances

    Requests access for balance data on accounts collected in this session.

    ownership

    Requests access for ownership data on accounts collected in this session.

    payment_method

    Requests permission for the creation of a payment method from an account collected in this session.

    transactions

    Requests access for transaction data on accounts collected in this session.

  • prefetchnullable array of enums

    Data features requested to be retrieved upon account creation.

    Possible enum values
    balances

    Requests to prefetch balance data on accounts collected in this session.

    ownership

    Requests to prefetch ownership data on accounts collected in this session.

    transactions

    Requests to prefetch transaction data on accounts collected in this session.

  • return_urlnullable string

    For webview integrations only. Upon completing OAuth login in the native browser, the user will be redirected to this URL to return to your app.

The Session object
{
  "id": "fcsess_1MwtnGLkdIwHu7ixs7NPQ7dq",
  "object": "financial_connections.session",
  "account_holder": {
    "customer": "cus_NiKSWdaFz2F6I0",
    "type": "customer"
  },
  "accounts": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/financial_connections/accounts"
  },
  "client_secret": "fcsess_client_secret_KRJTKvCY3IKoYTrW18EazcO3",
  "filters": {
    "countries": [
      "US"
    ]
  },
  "livemode": false,
  "permissions": [
    "balances",
    "payment_method"
  ]
}

Create a Session 

To launch the Financial Connections authorization flow, create a Session. The session’s client_secret can be used to launch the flow using Stripe.js.

Parameters

  • account_holderobjectRequired

    The account holder to link accounts for.

  • permissionsarray of stringsRequired

    List of data features that you would like to request access to.

    Possible values are balances, transactions, ownership, and payment_method.

  • filtersobject

    Filters to restrict the kinds of accounts to collect.

  • prefetcharray of enums

    List of data features that you would like to retrieve upon account creation.

    Possible enum values
    balances

    Requests to prefetch balance data on accounts collected in this session.

    ownership

    Requests to prefetch ownership data on accounts collected in this session.

    transactions

    Requests to prefetch transaction data on accounts collected in this session.

  • return_urlstring

    For webview integrations only. Upon completing OAuth login in the native browser, the user will be redirected to this URL to return to your app.

Returns

Returns the Session object.

POST /v1/financial_connections/sessions
curl https://api.stripe.com/v1/financial_connections/sessions \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "account_holder[type]"=customer \
  -d "account_holder[customer]"=cus_NiKSWdaFz2F6I0 \
  -d "permissions[]"=payment_method \
  -d "permissions[]"=balances \
  -d "filters[countries][]"=US
Response
{
  "id": "fcsess_1MwtnGLkdIwHu7ixs7NPQ7dq",
  "object": "financial_connections.session",
  "account_holder": {
    "customer": "cus_NiKSWdaFz2F6I0",
    "type": "customer"
  },
  "accounts": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/financial_connections/accounts"
  },
  "client_secret": "fcsess_client_secret_KRJTKvCY3IKoYTrW18EazcO3",
  "filters": {
    "countries": [
      "US"
    ]
  },
  "livemode": false,
  "permissions": [
    "balances",
    "payment_method"
  ]
}

Retrieve a Session 

Retrieves the details of a Financial Connections Session

Parameters

No parameters.

Returns

Returns a Session object if a valid identifier was provided, and raises an error otherwise.

GET /v1/financial_connections/sessions/:id
curl https://api.stripe.com/v1/financial_connections/sessions/fcsess_1MwtnGLkdIwHu7ixs7NPQ7dq \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "id": "fcsess_1MwtnGLkdIwHu7ixs7NPQ7dq",
  "object": "financial_connections.session",
  "account_holder": {
    "customer": "cus_NiKSWdaFz2F6I0",
    "type": "customer"
  },
  "accounts": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/financial_connections/accounts"
  },
  "client_secret": "fcsess_client_secret_KRJTKvCY3IKoYTrW18EazcO3",
  "filters": {
    "countries": [
      "US"
    ]
  },
  "livemode": false,
  "permissions": [
    "balances",
    "payment_method"
  ]
}

Transactions 

A Transaction represents a real transaction that affects a Financial Connections Account balance.

Endpoints