---
updatedAt: 2026-09-09T09:01:39.000Z
agentTools:
projectIndex: https://docs.bridgeapi.io/llms.txt
---
# Migration guide from 2019 to 2025 version
This page outlines the technical changes introduced in the latest API version, intended to assist developers in migrating and adapting to the updated functionality
### 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.
_The 2019 version is already deprecated and will reach its end-of-life on 31/12/2026._
# Structural changes
### API versioning and endpoints paths
* All endpoint paths now use `/v3` instead of `/v2`
* Set `Bridge-Version` header to `2025-01-15`
* 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_available`and `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
```json
{
"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](https://docs.bridgeapi.io/reference/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`
### Use Payment Links instead of Payment request
Payment Links offers the same possiblities than payment request. If you don't have an agrement to use payment request you need to switch to creating payment links.
### 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"
### Payment statuts on Payment Links
Payment status is a field at the payment link level called payment\_status.
This status can have four possible values :
๐ด not\_paid
๐ต in\_progress
๐ partially\_initiated\_in\_success
๐ข initiated\_in\_success
List of rules :
Base the status on the latest payment\_request.
For a payment made through a provider without an execution status (such as LCL for example), it should be ๐ข initiated\_in\_success if it is in PDNG.
For a payment made through a provider with an execution status, it should be ๐ต in\_progress if it is in PDNG.
For a bulk payment, the status should depend on the latest payment\_request:
if ACSC โ ๐ข initiated\_in\_success
if RJCT โ ๐ด not\_paid
if PART โ ๐ partially\_initiated\_in\_success
Those status are also available and sent by our webhook Payment Links - Payment Link updated this event is triggered when a Payment Link is updated.
### 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](https://docs.bridgeapi.io/docs/user-creation-authentication) section and [Users](https://docs.bridgeapi.io/reference/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](https://docs.bridgeapi.io/reference/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](https://docs.bridgeapi.io/docs/configure-1) section for more details.
* `account_types`: Defines the accounts to retrieve (`payment` by default, or `all`). Please read the [Account types and user experiences](https://docs.bridgeapi.io/docs/connect-user-journey) 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](https://docs.bridgeapi.io/reference/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
```json
{
"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](https://docs.bridgeapi.io/docs/webhooks-events) section for more details
### Item resource example
```json
{
"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](https://docs.bridgeapi.io/reference/items) Reference for more details.
### `item.refreshed` webhook example
```json
{
"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
```json
{
"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](https://docs.bridgeapi.io/reference/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](https://docs.bridgeapi.io/reference/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
```json
{
"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.
| Before | After |
| :------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------- |
| /v2/banks | /v3/providers |
| /v2/users (email & password) | /v3/aggregation/users (empty payload or external\_user\_id) |
| /v2/authenticate (email & password) | /v3/aggregation/authorization/token (user\_uuid or external\_user\_id) |
| /v2/connect/items/add/url
/v2/connect/items/sync
/v2/connect/items/edit/url | /v3/aggregation/connect-sessions |
| /v2/items | /v3/aggregation/items |
| /v2/accounts | /v3/aggregation/accounts |
| /v2/transactions
/v2/transactions/updated | /v3/aggregation/transactions |
| /v2/stocks
/v2/stocks/updated | /v3/aggregation/stocks |
| /v2/categories | /v3/aggregation/categories |
| /v2/insights/category | /v3/aggregation/insights/category |
| /v2/payment-requests | /v3/payment/payment-requests (prefer Payment Link: /v3/payment/payment-links) |
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`.