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

​
Prerequisites

Before starting, ensure you have:
  • A Formance stack with Connectivity module version ≥ 3.1 enabled
  • An Open Banking connector installed (Plaid, Tink, or Powens)

​
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.
The fields shown below are exhaustive. Some providers may require only a subset of these fields, while others may require all of them. Check the connector docs for your specific provider’s requirements.
curl -X POST '{SERVER_URL}/v3/payment-service-users' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -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 '{SERVER_URL}/v3/payment-service-users/{psuID}/connectors/{connectorID}/forward' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
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
Generate a secure authentication URL for the user to connect their bank account. 
curl -X POST '{SERVER_URL}/v3/payment-service-users/{psuID}/connectors/{connectorID}/create-link' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicationName": "Your App Name",
    "clientRedirectURL": "https://yourapp.com/banking"
  }'
Check the connector docs for your provider’s redirect URL requirements and restrictions.
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
See Frontend Integration Guidelines for detailed implementation guidance across different platforms.
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 '{SERVER_URL}/v3/payment-service-users/{psuID}/connectors/{connectorID}/link-attempts/{attemptID}' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
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. Access Account Data: 
# List accounts for a specific PSU
curl -X GET '{SERVER_URL}/v3/accounts' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -d '{ "$match": { "psu_id": "7ab143dd-e686-4fbe-a64d-11f67b40985d"}}'

# List all accounts (no filter)
curl -X GET '{SERVER_URL}/v3/accounts' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

# Get specific account details
curl -X GET '{SERVER_URL}/v3/accounts/{accountID}' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

# Get account balances
curl -X GET '{SERVER_URL}/v3/accounts/{accountID}/balances' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

​
Connection Management

​
List User Connections

View all connections for a specific user and connector: 
curl -X GET '{SERVER_URL}/v3/payment-service-users/{psuID}/connectors/{connectorID}/connections' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
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 '{SERVER_URL}/v3/payment-service-users/{psuID}/connectors/{connectorID}/connections/{connectionID}/update-link' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicationName": "Your App Name",
    "clientRedirectURL": "https://yourapp.com/banking"
  }'

​
Delete Operations

Delete a Specific Connection: 
curl -X DELETE '{SERVER_URL}/v3/payment-service-users/{psuID}/connectors/{connectorID}/connections/{connectionID}' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
Delete Entire User: 
curl -X DELETE '{SERVER_URL}/v3/payment-service-users/{psuID}' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
Deletion operations are permanent and cannot be undone. All related data (accounts, transactions, connections) will be permanently removed.

​
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