📘

Important

We recommend contacting our teams before planning a version migration to ensure that you have properly anticipated any potential impacts. This will allow us to assist you in the best possible way throughout the process.

Structural changes

API versioning and endpoints paths

• All endpoint paths now use /v3 instead of /v2
• Endpoint domains are designed to clearly reflect their associated features, such as https://api.bridgeapi.io/v3/payment, https://api.bridgeapi.io/v3/aggregation, and so on

Field handling

• null values are no longer returned in responses
• Lowercase responses (e.g., valid, invalid_creds) except for country code, currency code and STET statuses

Providers

The Bank abstraction has now been replaced by the Provider abstraction.

As a result,

• All instances of the bank_id field have been replaced with provider_id
• The https://api.bridgeapi.io/v2/banks endpoint is no longer supported. Please integrate the https://api.bridgeapi.io/v3/providers endpoint to fetch provider data and their associated information

Main differences between /v2/banks and /v3/providers:

Renaming

• ais capability becomes aggregation
• country becomes country_code (and is not duplicated anymore in name)
• parent_name becomes group_name

New fields

• Aggregation and payment capabilities are detailed in aggregation_metadata and payment_metadata.
  • execution_status_availableand release_status are now available in payment_metadata
  • release_status is now available in aggregation_metadata
• Health status of our providers by capability are detailed in health_status. So /banks/insights isn't supported anymore.
• Complementary information (segment, region and keywords) about the provider is available under tags
• logo_url is replaced by an images object with a logo field
• provider_environments indicates on which environment the provider is available (prod and/or sandbox)

Removed fields

authentication_type, form, url, is_highlighted, channel_type, authentication_page_url and authentication_page_url_mobile are no longer accessible.

Provider resource example

{
  "id": 120,
  "name": "Crédit Agricole Val de France",
  "country_code": "FR",
  "images": { // new
    "logo": "https://web.bridgeapi.io/img/banks-logo/fr/creditagricole-dsp2.png"
  },
  "group_name": "Crédit Agricole", // renaming
  "capabilities": [
    "aggregation",
    "account_check",
    "single_payment",
    "single_payment_scheduled",
    "bulk_payment_scheduled",
    "bulk_payment",
    "instant_single_payment"
  ],
  "payment_metadata": { // new
    "release_status": "active",
    "nb_max_transactions": 80,
    "max_size_label": 140,
    "multiple_dates_payments": true,
    "sender_iban_available": true,
    "provider_environments": [
      "prod"
    ],
    "execution_status_available": true
  },
  "aggregation_metadata": { // new
    "release_status": "active"
  },
  "health_status": { // new
    "single_payment": {
      "status": "healthy"
    },
    "aggregation": {
      "status": "healthy"
    }
  },
  "tags": { // new
    "keywords": [
      "ca"
    ],
    "segment": [
      "b2c",
      "b2b"
    ],
    "region": [
      "Val de France"
    ]
  }
}

Please read Providers Reference for more details.

Payment

Changes to beneficiary and user

The name field is no longer supported. The API now requires either a first_name / last_name pair or a company_name

Payment request callback URL

Only one callback URL, callback_url, is now supported during payment request creation. The fields successful_callback_url and unsuccessful_callback_url are no longer supported

Optional label field

The label field is now optional for applications without a payment account. If not provided, the label will default to "Bridge Payment dd-mm"

Renaming

bank_id becomes provider_id

Aggregation

Users and authorization

Creating a user no longer requires an email/password pair.

You can optionally include an external_user_id when creating users. This allows you to authenticate them and search for them in our dashboard using this reference.

Generate authorization tokens by sending a POST request to: https://api.bridgeapi.io/v3/aggregation/authorization/token.

Please read User creation and authentication section and Users Reference for more details.

📘

During migration, you will need to authenticate your old users (created with an email/password pair) using their Bridge user_uuid on the new API version

Connect sessions

New unique endpoint

Create all your Connect links by sending a POST request to: https://api.bridgeapi.io/v3/aggregation/connect-sessions

Please read Connect sessions Reference for more details.

Parameters updates

• prefill_email becomes user_email
• bank_id becomes provider_id
• callback_url: The callback URL for user session completion can now be defined for each session. Please read the Configure section for more details.
• account_types: Defines the accounts to retrieve (payment by default, or all). Please read the Account types and user experiences section for more details.
• item_id: To manage the life cycle of an existing item
  • Resolve errors for items in a non-zero status. You don't need to interpret the item's status anymore, the Connect will automatically adapt for each situation (invalid credentials, strong customer authentication, pro validation...)
  • Modify account_types

All parameters need to be send through the request body. Please read the Connect sessions Reference for more details.

❗️

Migration impacts

Depending on your account_types needs and the configuration of your current application, migrate your old items on the new API version can impact the user experience and the collected data

Account selection

• Users can now disable accounts during Connect sessions
• Disabled accounts have data_access: disabled, which means:
  • Associated IBAN, balances, loan details, transactions, and stocks are no longer accessible via our API
  • Fields such as balance, nb_deleted_transactions, nb_new_transactions, and nb_updated_transactions are no longer included in the item.account.updated webhook

📘

During migration, regardless of the API version used, disabled accounts will be impacted in the same way (e.g., obfuscation, transaction/stock filtering, webhooks, etc.).

Reminder: Starting from version 2025-01-15, null fields are no longer exposed. This behavior differs from version 2021-06-01, where null fields are still present.

Webhook example for a disabled account

{
  "content": {
    "account_id": 47050682,
    "data_access": "disabled",
    "item_id": 9947120,
    "user_uuid": "9b2a711e-7441-4581-9514-0ccaa3ea5e33"
  },
  "timestamp": 1729694049981,
  "type": "item.account.updated"
}

Item resource updates

New item fields

• account_types: payment or all
• created_at: Item creation timestamp
• last_try_refresh: Timestamp of the last refresh attempt
• last_successful_refresh: Timestamp of the last successful refresh

Webhook updates

item.refreshed now includes:

• account_types : payment or all
• refresh_trigger: connect, api or scheduler. Please read the Webhooks section for more details

Item resource example

{
      "id": 10215554,
      "status": 1010,
      "status_code_info": "sca_required_webview",
      "status_code_description": "Your bank requires you to renew your account synchronization to confirm your identity.",
      "provider_id": 122, // renaming
      "account_types": "all", // new
      "last_successful_refresh": "2024-12-06T06:56:35.191Z", // new
      "last_try_refresh": "2024-12-06T06:56:14.000Z", // new
      "created_at": "2024-12-04T08:51:54.770Z" // new
    }

Please read Items Reference for more details.

item.refreshed webhook example

{
  "content": {
    "account_types": "all", // new
    "full_refresh": true,
    "item_id": 10215554,
    "refresh_trigger": "connect", // new
    "status_code": 0,
    "status_code_info": "OK",
    "user_uuid": "24b0a87a-96ba-4d96-b39f-244fcb13969c"
  },
  "timestamp": 1733302472225,
  "type": "item.refreshed"
}

Account resource updates

New fields

• data_access: Indicates if the account is enabled or disabled
• last_refresh_status: Status of the last refresh attempt (successful or failed)
• pro: Replaces is_pro to indicate if this account is a business account

Removed fields

status, status_code_info, is_paused and saving_details are no longer accessible on the account resource.

Simplified account types

Supported types:

• checking
• card
• savings
• brokerage
• loan
• life_insurance
• pea: Replaces shared_saving_plan
• unknown

The pending and special types have been removed and replaced by unknown.

Simplified rules

• The balances of accounts of type loan are now returned with the sign provided by the provider. So there is no longer a rule that returns the absolute value of the balance for certain account types.
• Temporary accounts created during item creation are no longer accessible. These accounts typically have names like "Pending..." and a balance of 0. Going forward, accounts will only be exposed once they have been fully fetched from the provider.

Account resource example

{
      "id": 48546984,
      "name": "Crédit Immo",
      "balance": 427928,
      "updated_at": "2024-12-06T08:45:38.643Z",
      "last_refresh_status": "successful", // new
      "type": "loan",
      "currency_code": "EUR",
      "item_id": 10224815,
      "provider_id": 574, // renaming
      "loan_details": {
        "next_payment_date": "2025-01-01",
        "next_payment_amount": 2772,
        "maturity_date": "2042-01-01",
        "opening_date": "2022-01-01",
        "interest_rate": 2.42,
        "borrowed_capital": 500000,
        "repaid_capital": 72072,
        "remaining_capital": 427928,
        "total_estimated_interests": 103939.7239008639
      },
      "data_access": "enabled", // new
      "pro": false, // renaming
    },

Please read Accounts Reference for more details.

Transactions endpoint updates

New unique transactions endpoint

Fetch transactions by sending a GET request to: https://api.bridgeapi.io/v3/aggregation/transactions.

This endpoint supports the since parameter to retrieve transactions updated before a specific timestamp. Additionally, you can use the min_date and max_date parameters to fetch transactions with a date earlier or later than the specified values.

As a result, /transactions/updated is no longer exposed.

Please read Transactions Reference for more details.

Fields renaming

• is_deleted becomes deleted
• is_future becomes future
• bank_description becomes provider_description

New operation_type field

operation_type can take the following values: card, deferred_debit_card, transfer, direct_debit, check, withdrawal, deposit, unknown

Removed field

show_client_side is no longer accessible on the transaction resource.

Deferred debit cards

Users with deferred debit cards have a dedicated card account where card transactions are recorded throughout the month. At the end of the month, compensatory transactions may be processed to reconcile the card and checking accounts. These transactions adjust balances between the accounts.

• Card Transactions
  • operation_type: card
  • Represent individual purchases made with the card
• Compensatory Transactions
  • operation_type: deferred_debit_card
  • Adjust balances between the card and checking accounts at the end of the month

Recommendation
To prevent user confusion and the perception of duplicate transactions, consider hiding or displaying separately the deferred_debit_card transactions.

Transaction resource example

{
      "id": 24000190448633,
      "clean_description": "Vir Sepa M John Doe Virement Vers Livret A",
      "provider_description": "VIR SEPA M JOHN DOE - VIREMENT VERS LIVRET A", // renaming
      "amount": -200,
      "date": "2024-09-30",
      "booking_date": "2024-09-30",
      "updated_at": "2024-12-06T08:46:10.065Z",
      "currency_code": "EUR",
      "deleted": false, // renaming
      "category_id": 326,
      "operation_type": "transfer", // new
      "account_id": 48546980,
      "future": false // renaming
    }

New unique stocks endpoint

Fetch stocks by sending a GET request to: https://api.bridgeapi.io/v3/aggregation/stocks.

This endpoint supports the since parameter to retrieve stocks updated before a specific timestamp.

Non exhaustive mapping of endpoints (be careful, payload may be different)

If you are using Bankin-Version header please replace it with Bridge-Version header.

The whole Transfer product has been replace by Payment which can handle single payment and bulks payments, as well as scheduled payments.

Nested resources in responses has been removed (example: item and bank in account response, account in transaction response, etc...) as well as the matching resource_uri.