Access transaction data for a Financial Connections account
Beta

Learn how to access an account’s transactions with your user’s permission.

Note

Access to transaction data is available as part of a US private beta. You can get started immediately with test mode, and request access to live-mode.

The Financial Connections API allows you to request, retrieve, and refresh the pending, posted, and voided transactions of a Financial Connections Account. Use transaction data to build a variety of products and solutions, such as:

Expediting the underwriting process and improving access to credit and other financial services for your users.
Mitigating fraud and reducing the risk of onboarding new users by evaluating a user’s transaction history, and understanding cash inflows and outflows from their financial accounts.
Helping your users track expenses, handle bills, and manage their finances.

You must specify the API Version and add the string ; financial_connections_transactions_beta=v1 to all your requests as indicated in the code snippets below.

To listen to the financial_connections.account.refreshed_transactions event, create an endpoint with the latest financial_connections_transactions_beta version. You can use the same URL as any previous webhook endpoint.

Request access to an account’s transactions
Server-side

You must collect an account before you can access transaction data in the Financial Connections API. To learn more about how to collect a Financial Connections account, consult the integration guide most relevant to your use case: accept payments, facilitate Connect payouts, or build other-data powered products.

When collecting an account, you must specify the data you need to access with the data permissions parameter and receive a user’s consent to access it within the authentication flow.

We recommend using a Financial Connections Session to request permission to retrieve transactions for an account.

Optionally, you can request to prefetch transactions, which retrieves transactions on account creation. The prefetch parameter saves you from making another API call to retrieve data after account creation and reduces the latency of data retrieval.

Command Line

curl https://api.stripe.com/v1/financial_connections/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -H "Stripe-Version: 2023-10-16; financial_connections_transactions_beta=v1" \
  -d "account_holder[type]"="customer" \
  -d "account_holder[customer]"="cus_M3y5INkE1fqdoF" \
  -d "permissions[]"="transactions" \
  -d "prefetch[]"="transactions"

The response will look similar to:

{
  "id": "fcsess_1LXRZiGxLVUXRs6HEpnbRACv",
  "object": "financial_connections.session",
  "account_holder": {
    "customer": "cus_M3y5INkE1fqdoF",
    "type": "customer"
  },
  "accounts": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/financial_connections/accounts"
  },
  "client_secret": "fcsess_client_secret_4h8btITTyVR6InHnq0aRuyt2",
  "livemode": true,
  "permissions": [
    "transactions"
  ]
}

Retrieve an account’s transactions with an ongoing subscription
Server-side

When you collect an account, the account will have the transactions permission granted.

{
  "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
  "object": "financial_connections.account",
  "account_holder": {
    "customer": "cus_Lv1Ue0s0hBnI7R",
    "type": "customer"
  },
  "balance": null,
  "balance_refresh": null,
  "category": "cash",
  "created": 1647973464,
  "display_name": "Savings",
  "institution_name": "Test Bank",
  "last4": "2222",
  "livemode": true,
  "ownership": null,
  "ownership_refresh": null,
  "permissions": [
    "transactions"
  ],
  "status": "active",
  "subcategory": "savings",
  "subscriptions": [],
  "supported_payment_method_types": [
    "us_bank_account"
  ],
  "transaction_refresh": null
}

The transaction_refresh field on the account describes the most recent attempt to refresh the account’s transactions, and is initially null. If you opted to prefetch transactions, an asynchronous refresh starts during account creation, and you won’t need to make a refresh call until you need updated data.

The account also has an empty subscriptions array. We recommend subscribing to ongoing refreshes of account transactions to receive the latest transaction data available.

Use the subscription endpoint to subscribe to transactions on the account:

Command Line

curl https://api.stripe.com/v1/financial_connections/accounts/:id/subscribe \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -H "Stripe-Version: 2023-10-16; financial_connections_transactions_beta=v1" \
  -d "features[]"="transactions"

This returns an account resource with transactions in the subscriptions field.

{
  "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
  "object": "financial_connections.account",
  "account_holder": {
    "customer": "cus_Lv1Ue0s0hBnI7R",
    "type": "customer"
  },
  "balance": null,
  "balance_refresh": null,
  "category": "cash",
  "created": 1647973464,
  "display_name": "Savings",
  "institution_name": "Test Bank",
  "last4": "2222",
  "livemode": true,
  "ownership": null,
  "ownership_refresh": null,
  "permissions": [
    "transactions"
  ],
  "status": "active",
  "subcategory": "savings",
  "subscriptions": [
    "transactions"
  ],
  "supported_payment_method_types": [
    "us_bank_account"
  ],
  "transaction_refresh": {
    "id": "fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf",
    "last_attempted_at": 1651784999,
    "next_refresh_available_at": null,
    "status": "pending",
  }
}

Stripe automatically refreshes an account’s transactions when you subscribe to an account.

The time required to fetch the initial transaction data varies depending on the financial institution, but generally completes within seconds.

After Stripe retrieves transactions from the relevant financial institution, the Financial Connections account resource shows the transaction_refresh.status field as succeeded.

After the refresh succeeds, Stripe emits a financial_connections.account.refreshed_transactions webhook, which includes the relevant Financial Connections account object.

Retrieve transactions from the list transactions endpoint after the background process succeeds:

Command Line

curl https://api.stripe.com/v1/financial_connections/transactions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "GET" \
  -H "Stripe-Version: 2023-10-16; financial_connections_transactions_beta=v1" \
  -d "account"="fca_1LDYuMGxLVUXRs6HW0lrat9T" \
  -d "limit"=3

The response includes paginated transactions available on the account. Stripe can currently return up to the last 180 days of transaction data on an account.

{
  "object": "list",
  "data": [
    {
      "id": "fctxn_1LXp9RGxLVUXRs6HtTSVfxse",
      "object": "financial_connections.transaction",
      "account": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
      "amount": -1000,
      "currency": "usd", 
      "description": "Rocket Rides",
      "livemode": true,
      "status": "posted",
      "status_transitions": {
        "posted_at": 1651784999,
        "void_at": null
      },
      "transacted_at": 1651784999,
      "transaction_refresh": "fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf",
      "updated": 1651784999
    },
    {...},
    {...}
  ],
  "has_more": false,
  "url": "/v1/financial_connections/transactions"
}

The status of a transaction can be one of pending, posted, or void. Information included in the description field varies, but can include metadata such as the merchant name.

Stripe initiates daily subsequent transaction refreshes, and notifies you when additional transaction data is available by returning a financial_connections.account.refreshed_transactions event.

You can start, cancel, and resume a subscription at any point.

To cancel a subscription, call the unsubscribe endpoint:

Command Line

curl https://api.stripe.com/v1/financial_connections/accounts/:id/unsubscribe \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -H "Stripe-Version: 2023-10-16; financial_connections_transactions_beta=v1" \
  -d "features[]"="transactions"

To resume the subscription, call the subscription endpoint again.

Retrieve only new or updated transaction data since your last refresh
Server-side

You may wish to retrieve only new transaction data since your last pull. For example, some users save previously retrieved transaction data to their database, and subsequently merge new or updated data as it becomes available.

To retrieve only new or updated transaction data since your last refresh, pass the transaction_refresh identifier provided by your last observed financial_connections.account.refreshed_transactions webhook event object to the transaction_refresh.after parameter:

Command Line

curl https://api.stripe.com/v1/financial_connections/transactions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "GET" \
  -H "Stripe-Version: 2023-10-16; financial_connections_transactions_beta=v1" \
  -d "account"="fca_1LDYuMGxLVUXRs6HW0lrat9T" \
  -d "transaction_refresh[after]"="fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf" \
  -d "limit"=3

The response lists paginated transactions that have been updated or created by a transaction refresh that took place after the passed transaction refresh, and won’t include previously retrieved transactions.

The following is an illustrative integration that only retrieves and records new or updated transaction data:

@app.route('/stripe_webhooks', methods=['POST'])
def webhook():
    event = None
    payload = request.data
    sig_header = request.headers["STRIPE_SIGNATURE"]

    try:
        event = stripe.Webhook.construct_event(payload, sig_header, endpoint_secret)
    except ValueError as e:
        # Invalid payload
        raise e
    except stripe.error.SignatureVerificationError as e:
        # Invalid signature
        raise e

    if event["type"] == "financial_connections.account.refreshed_transactions":
        account = event["data"]["object"]
        sync_transactions(account)

    return jsonify(success=True)


def sync_transactions(account):
    # Fetches from the DB the last transaction_refresh id observed for this account
    last_observed_transaction_refresh = get_previous_transaction_refresh(
        key=account["id"]
    )

    transactions = get_transactions(
        account=account["id"],
        transaction_refresh={"after": last_observed_transaction_refresh},
    )  # Calls /v1/financial_connections/transactions

    # We know every transaction is either new or updated because of the `transaction_refresh` filter in the list endpoint
    for transaction in transactions:
        record_transaction(transaction)  # Saves the transaction to the DB

    # Updates the last observed transaction_refresh for this account
    set_previous_transaction_refresh(
        key=account["id"], value=account["transaction_refresh"]["id"]
    )

Retrieve an account’s transactions on demand
Server-side

You can call the account refresh endpoint to initiate an on-demand pull or refresh of account transactions. This can be in addition to, or instead of subscribing to ongoing updates to an account’s transactions. This causes Stripe to retrieve the most up-to-date transaction data available from the financial institution.

Command Line

curl https://api.stripe.com/v1/financial_connections/accounts/:id/refresh \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST" \
  -H "Stripe-Version: 2023-10-16; financial_connections_transactions_beta=v1" \
  -d "features[]"="transactions"

As with the subscription option, the response describes the current status of the Financial Connections account. In particular, transaction_refresh.status is now pending:

{
  "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
  "object": "financial_connections.account",
  "permissions": [
    "transactions"
  ],
  "subscriptions": [],
  "transaction_refresh": {
    "id": "fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf",
    "last_attempted_at": 1651784999,
    "next_refresh_available_at": null,
    "status": "pending",
  },
  // …
}

If the background process succeeds, the Financial Connections account resource shows the transaction_refresh.status as succeeded.

{
  "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
  "object": "financial_connections.account",
  "permissions": [
    "transactions"
  ],
  "subscriptions": [],
  "transaction_refresh": {
    "id": "fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf",
    "last_attempted_at": 1651784999,
    "next_refresh_available_at": 1651785000,
    "status": "succeeded"
  },
  // …
}

Additionally, Stripe emits a financial_connections.account.refreshed_transactions webhook, which includes the relevant Financial Connections account object.

After the completion of a transaction refresh, Stripe sets the availability of transaction refreshes through the next_refresh_available_at timestamp field.

Check the next_refresh_available_at field on the transaction_refresh hash before initiating a subsequent transaction refresh to make sure that transaction refreshes are currently available. If you attempt a refresh while the value is null (as is always the case when the refresh is pending) or the current time is less than the next_refresh_available_at timestamp, the refresh won’t be initiated.

After Stripe successfully retrieves transactions from the financial institution, you can retrieve transactions:

Command Line

curl https://api.stripe.com/v1/financial_connections/transactions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "GET" \
  -H "Stripe-Version: 2023-10-16; financial_connections_transactions_beta=v1" \
  -d "account"="fca_1LDYuMGxLVUXRs6HW0lrat9T" \
  -d "limit"=3

The response includes up to the last 180 days of paginated transactions available on the account.

{
  "object": "list",
  "data": [
    {
      "id": "fctxn_1LXp9RGxLVUXRs6HtTSVfxse",
      "object": "financial_connections.transaction",
      "account": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
      "amount": -1000,
      "currency": "usd", 
      "description": "Rocket Rides",
      "livemode": true,
      "status": "posted",
      "status_transitions": {
        "posted_at": 1651784999,
        "void_at": null
      },
      "transacted_at": 1651784999,
      "transaction_refresh": "fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf",
      "updated": 1651784999
    },
    {...},
    {...}
  ],
  "has_more": false,
  "url": "/v1/financial_connections/transactions"
}

Access transaction data for a Financial Connections accountBeta

Note

Request access to an account’s transactionsServer-side

Retrieve an account’s transactions with an ongoing subscriptionServer-side

Retrieve only new or updated transaction data since your last refreshServer-side

Retrieve an account’s transactions on demandServer-side

OptionalRequest an account’s transactions when adding an account to accept an ACH Direct Debit paymentServer-side

Access transaction data for a Financial Connections account
Beta

Request access to an account’s transactions
Server-side

Retrieve an account’s transactions with an ongoing subscription
Server-side

Retrieve only new or updated transaction data since your last refresh
Server-side

Retrieve an account’s transactions on demand
Server-side

OptionalRequest an account’s transactions when adding an account to accept an ACH Direct Debit payment
Server-side