Guides
Dashboard Bridge

Financial Data Aggregation

Suggest Edits

Security and Configuration

  • IP Whitelisting: Ensure that your server IP addresses are authorized in the Bridge dashboard to secure API interactions.
  • Webhook Security: Whitelist Bridge's IP addresses (63.32.31.5, 52.215.247.62, 34.249.92.209) to validate incoming webhook requests.
  • Application Customization: Configure your application's logo and highlight preferred banks in the dashboard to enhance user experience.
  • Data Encryption: Implement encryption for all banking data retrieved via the API to maintain data confidentiality.
  • Production Readiness: Coordinate with the Sales team to schedule your production launch and ensure compliance with regulatory requirements.
  • API Response Handling: Interpret HTTP status codes as outlined in the API basics to handle responses appropriately.

Bridge Users Management

  • User Data Mapping: Store Bridge users in a table linked to your internal user records using external_user_id for seamless integration.
  • Authentication: Authenticate each Bridge user before making API calls by generating an authorization token.
  • User Deletion: Delete Bridge users when customers cancel their subscriptions to ensure data is not retained unnecessarily.

Item Synchronization and Lifecycle

  • Connect Flow Parameters: After the Bridge Connect flow, retrieve parameters like uuid, item_id, success, step, and optionally context from the redirection URL to tailor the user journey.
  • Item Status Monitoring: Regularly check the status of items to identify connection issues and manage errors effectively.
  • Status Interpretation: Interpret item statuses daily and before fetching banking data to ensure accurate data synchronization.
  • User Communication: Display status_code_description to inform users about the status of their connections. Adjust the Accept-Language header to retrieve descriptions in the desired language.
  • Strong Customer Authentication (SCA): For items with status 1010, prompt users to complete SCA through Bridge Connect.
  • Persistent Errors: If an item with status 1003 does not return to a functional state (0 status) after 24 hours, contact Bridge support for assistance.
  • Business Account Validation: For items with status 1100, request users to validate their business accounts via Bridge Connect.
  • Credential Updates: For items with status 402, prompt users to update their banking credentials through Bridge Connect.
  • Support Facilitation: Store the item_id to assist your support team in investigating issues and communicating with Bridge's Help Center.

Data Fetching

  • Account Verification: Before fetching transactions, check for any new or deleted accounts to maintain data consistency.
  • Data Storage: Store the complete data model, including users, items, accounts, and transactions, as the API does not provide real-time data.
  • Identifier Management: Store the id of each item, account, and transaction to ensure data uniqueness and integrity.
  • Efficient Data Retrieval: Use the filter since to fetch only new or updated transactions daily.
  • Transaction Display: Decide whether to display future transactions with future = true based on your application's requirements.

Checklist for a Complete Integration

User Lifecycle Flow

✅ User Creation

  1. Call POST /v3/aggregation/users with required fields.
  2. Securely store the user uuidreturned.

✅ User Authentication

  1. Call POST /v3/aggregation/authorization/token.
  2. Keep in mind that this access_tokenreturned is valid 2h.
  3. Renew the access_token if needed by placing the user uuid in the body of the call.

Bank Connection Flow

✅ Launch Bridge Connect

  1. Create a Connect link with POST /v3/aggregation/connect-sessions.
  2. Control redirection after the synchronization with a callback_url.
  3. Make sure the access_tokenis correctly sent to authenticate the call.
  4. Customize the Bridge Connect through the Bridge Dashboard.
  5. Test full flow using sandbox test bank : Demo Bank.

When calling POST/v3/aggregation/connect-sessions, you must send the user_email field:

This field is mandatory, except in temporary synchronization flows. It enables Bridge to contact the end user in critical cases (e.g., change of General Conditions of Service).
⚠️ You may use a generic or proxy email if preferred, but do not omit it in long-lived connections.

(See: Create Connect Session – Bridge Docs)

Test cases:

  • Successful link
  • Cancelled flow
  • MFA scenario

Aggregation Data Flow

Accounts

  1. Retrieve via GET /v3/aggregation/accounts.
  2. Exclude accounts where data_access: "disabled".
  3. Use last_refresh_status to validate update success:
    1. successful if account.updated_at >= item.last_try_refresh
    2. failed if not
  4. Track account category, type, and status.

Transactions

  1. Fetch using GET /v3/aggregation/transactions.
  2. Handle pagination with starting_after.
  3. Display future = true transactions in a planned section (if needed otherwise exclude all transactions future = true).
  4. Group or label by operation_type.
  5. Filter transactions with sincefilter more information how to do so here.
  6. Handling operation_type and CDD (Deferred Debit Cards).

The operation_type field is key for properly interpreting transactions. It offers a more objective classification than categories and enables correct handling of CDD (cartes à débit différé) behaviors.

✅ Common operation_type values:

🧠 Key Use Case: deferred_debit_card

  • Role: Identifies aggregated compensation lines between the card account and the current account.
  • Where: May appear on either account, as either a monthly debit or individual entries, depending on the institution.

Recommendation:

  1. Either display them distinctly in your UI, as they do not represent new spendings, or
  2. Hide them from users if the detailed transactions are shown elsewhere.

🏷️ card transactions

  • Represent actual card usage (both immediate and deferred debit).
  • Use these for showing day-to-day card purchases.

Items

  1. Monitor item status.
  2. Handle 1100 (Pro Bank Identity Verification) :

Item status 1100 indicates the user has connected a professional (pro) bank account requiring identity verification. If not properly handled:

  1. All sensitive data will be obfuscated (e.g., values shown as XXXX).
  2. The 1100 status is not delivered via webhooks, so it must be proactively polled.

✔️ How to Handle It
Step 1 – Authenticate & Create User
Ensure the user is authenticated. If they do not yet exist, create them using POST /v3/aggregation/users.

Step 2 – Retrieve Items
Call GET /v3/aggregation/items and inspect the status field.
If status === 1100, proceed to Step 3.

Step 3 – Create a New Connect Session
Create a new Connect link via POST /v3/aggregation/connect-sessions, and include the item_id in the body.
This sends the user to a specific flow to complete identity verification.

🧠 Pro tip: Set up a daily or hourly routine to poll items for status: 1100, since you won’t receive a webhook.


Error Handling

  1. Catch and log error_code, error_type, and messages.
  2. Handle common errors
  3. Implement retry with exponential backoff for 5xx errors.

Webhooks

  1. Implement webhook receivers for:
    1. account.updated
    2. transaction.created
    3. item.status_changed
  2. Secure your webhook endpoint (signature validation recommended).

Monitoring & Support

  1. Subscribe to live provider incident feed: Connectors Incidents.
  2. Sign up for Bridge product & status communications.
  3. Create a Zendesk account to submit or manage tickets.
  4. Track your open tickets here: Manage Support Requests.


✅ Ready to Go Live?
Once these checks are green, reach out via the Bridge Dashboard to request production access.
Don’t forget to test with a real institution in production before going fully live.

Updated 3 days ago