Getting Started with Open Banking

This guide walks you through implementing Open Banking with Formance, from creating users to accessing bank account data.

Overview#

The Open Banking workflow consists of these key steps:

1. Create a Payment Service User (PSU) - Represents your end user
2. Forward PSU to Connector - Register the user with your Open Banking provider
3. Create Authentication Link - Generate a secure URL for bank connection
4. User Authentication - User connects their bank account via the provider's interface
5. Access Account Data - Retrieve accounts, balances, and transactions

Implementation#

Step 1: Create a Payment Service User#

Create a Payment Service User (PSU) to represent the end user who will connect their bank account.

curl -X POST $FORMANCE_API_URL/api/payments/v3/payment-service-users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "contactDetails": {
      "email": "john.doe@example.com",
      "phoneNumber": "+1234567890",
      "locale": "en_US"
    },
    "address": {
      "streetName": "Main Street",
      "streetNumber": "123",
      "city": "New York",
      "region": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "metadata": {
      "customerID": "cust_12345"
    }
  }'

Response:

{
  "data": "5968b0e2-06da-4552-8ad0-c484706bd2d7"
}

Save the returned PSU ID for subsequent steps.

Step 2: Forward PSU to Connector#

Register the PSU with your Open Banking connector to prepare them for authentication.

curl -X POST $FORMANCE_API_URL/api/payments/v3/payment-service-users/<PSU_ID>/connectors/<CONNECTOR_ID>/forward

Parameters:

• psuID: The PSU ID from Step 1
• connectorID: Your Open Banking connector ID (find this in your Formance Console under Connectors)

Response:

204 No Content

Step 3: Create Authentication Link#

Generate a secure authentication URL for the user to connect their bank account.

curl -X POST $FORMANCE_API_URL/api/payments/v3/payment-service-users/<PSU_ID>/connectors/<CONNECTOR_ID>/create-link \
  -H "Content-Type: application/json" \
  -d '{
    "applicationName": "Your App Name",
    "clientRedirectURL": "https://yourapp.com/banking"
  }'

Response:

{
  "attemptID": "xyz789",
  "link": "https://secure.plaid.com/hl/authentication-link"
}

Step 4: User Authentication Flow#

Direct the user to the authentication link to connect their bank account.

Your Application:

Redirect the user to the link from Step 3

User Experience (Provider Interface): The user will:

1. Select their bank from the provider's interface and be redirected to the bank's interface
2. Enter credentials or complete OAuth flow with their bank
3. Grant permissions for account access
4. See confirmation that the connection was successful

Return to Your Application:

• The provider automatically redirects the user back to your clientRedirectURL
• Check the authentication status by requesting the link attempt:

curl -X GET $FORMANCE_API_URL/api/payments/v3/payment-service-users/<PSU_ID>/connectors/<CONNECTOR_ID>/link-attempts/<ATTEMPT_ID>

Response:

{
  "data": {
    "id": "adc80553-02df-4d42-ad88-44099af38580",
    "psuID": "7ab143dd-e686-4fbe-a64d-11f67b40985d",
    "connectorID": "eyJQcm92aWRlciI6InBvd2VucyIsIlJlZmVyZW5jZSI6ImMxMTMyYjg0LTdmYTEtNDRhZS1hZmRjLTBjMWZjMjIyYTIyYSJ9",
    "createdAt": "2025-09-25T15:05:04.316284Z",
    "status": "completed",
    "clientRedirectURL": "https://console.v3.staging.formance.cloud/knonmzexcoal/vayn?region=staging.formance.cloud",
    "error": null
  }
}

• Use the status field to determine if the authentication was successful

Step 5: Access Connected Accounts#

Once the connection is established, you can access the user's account data.

List accounts for a specific PSU:

curl -X GET $FORMANCE_API_URL/api/payments/v3/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "$match": {
      "psu_id": "7ab143dd-e686-4fbe-a64d-11f67b40985d"
    }
  }'

List all accounts (no filter):

curl -X GET $FORMANCE_API_URL/api/payments/v3/accounts

Get specific account:

curl -X GET $FORMANCE_API_URL/api/payments/v3/accounts/<ACCOUNT_ID>

Get account balances:

curl -X GET $FORMANCE_API_URL/api/payments/v3/accounts/<ACCOUNT_ID>/balances

Connection Management#

List User Connections#

View all connections for a specific user and connector:

curl -X GET $FORMANCE_API_URL/api/payments/v3/payment-service-users/<PSU_ID>/connectors/<CONNECTOR_ID>/connections

Response:

{
  "cursor": {
    "pageSize": 15,
    "hasMore": false,
    "data": [
      {
        "connectionID": "conn_456def789",
        "connectorID": "plaid_prod_001",
        "createdAt": "2024-01-15T10:30:00Z",
        "dataUpdatedAt": "2024-01-15T10:35:00Z",
        "status": "ACTIVE",
        "error": null,
        "metadata": {}
      }
    ]
  }
}

Monitor Connection Status#

Set up webhook handlers to receive notifications about connection status changes. You'll receive events when users complete authentication, when new data is synced, or when connections are lost.

Refresh Stale Connections#

If a connection becomes stale, generate a new authentication link:

curl -X POST $FORMANCE_API_URL/api/payments/v3/payment-service-users/<PSU_ID>/connectors/<CONNECTOR_ID>/connections/<CONNECTION_ID>/update-link \
  -H "Content-Type: application/json" \
  -d '{
    "applicationName": "Your App Name",
    "clientRedirectURL": "https://yourapp.com/banking"
  }'

Delete Operations#

Delete a specific connection:

curl -X DELETE $FORMANCE_API_URL/api/payments/v3/payment-service-users/<PSU_ID>/connectors/<CONNECTOR_ID>/connections/<CONNECTION_ID>

Delete entire user:

curl -X DELETE $FORMANCE_API_URL/api/payments/v3/payment-service-users/<PSU_ID>

Frontend Integration Guidelines#

Browser Integration#

For web applications:

• Use full page redirects - Do not use iframes as they're not compatible with all bank redirections
• Follow provider-specific browser integration guidelines

Mobile Integration#

For mobile applications:

• Android: Use Chrome Custom Tabs for the authentication flow
• iOS: Use SFSafariViewController for the authentication flow
• Avoid using in-app webviews as they may not support all authentication flows

Provider-Specific Guidelines#

Each Open Banking provider has specific integration requirements:

• Plaid: Standard OAuth implementation with redirect URL restrictions
• Powens: Specific webview browser integration guidelines
• Tink: Platform-specific optimization guides for Android and iOS