omnibank/bridge API reference

Omnibank\Bridge

Api class

final class Api Api.php:23

Bridge API v3 (bridgeapi.io): every call with the application's Client-Id, Client-Secret and Bridge-Version; a user's with the user's access token too (Bearer, about two hours: a new one is asked when it is past).

Webhooks: Bridge signs them in BridgeApi-Signature, "v1=<HMAC-SHA256 of the body with the webhook secret, hex>", several comma-separated while a secret is rotated. That reading is an assumption until checked against a real sandbox webhook.

const HOST = 'https://api.bridgeapi.io'

const VERSION = '2025-01-15'

const SIGNATURE_HEADER = 'BridgeApi-Signature'

const WEBHOOK_TOLERANCE = 300

How far a webhook's timestamp may be from now, in seconds (the webhook_tolerance option).

Api::__construct()

public function __construct(readonly HttpClientInterface $http, readonly string $clientId, readonly string $clientSecret, readonly string $version = self::VERSION, readonly ?string $webhookSecret = null, readonly string $host = self::HOST, readonly int $timeout = 30, readonly int $webhookTolerance = self::WEBHOOK_TOLERANCE)

Api::createUser()

public function createUser(string $externalUserId): array

Api::authorize()

public function authorize(string $userUuid): array

Api::token()

public function token(Connection $connection): string

The user's access token: the one in the connection's state while it holds (a minute to spare), a new one for its user otherwise.

Api::call()

public function call(string $method, string $path, ?string $token = null, ?array $body = null, array $query = []): array

$body

JSON

Throws

ProviderException when Bridge refuses (4xx)

Throws

UnavailableException when Bridge cannot be reached or fails (network, 5xx, 429)

Api::verify()

public function verify(string $body, ?string $header): void

Throws

InvalidNotificationException

Api::sign()

public static function sign(string $body, string $secret): string

The signature Bridge would send for this body (upper-case hex), without its "v1=".

BridgeGatewayFactory class

final class BridgeGatewayFactory extends GatewayFactory BridgeGatewayFactory.php:31

Bridge (bridgeapi.io, by Perspecteev), its API v3: the user connects their banks in a Bridge Connect session; accounts, balances and transactions are read with the user's access token; item.* webhooks say when the data is fresh or the consent must be renewed. The connection's state keeps the Bridge user (user_uuid, external_user_id) and its last token. No transfers in this version.

options: client_id: '%env(BRIDGE_CLIENT_ID)%' client_secret: '%env(BRIDGE_CLIENT_SECRET)%' version: '2025-01-15' # Bridge-Version webhook_secret: '%env(BRIDGE_WEBHOOK_SECRET)%' # for notify() webhook_tolerance: 300 # seconds a webhook's timestamp may be from now callback_url: null # when connect() is given no return URL country_code: FR # the banks the connect session lists

Options

Mapper class

final class Mapper Mapper.php:12

Bridge's accounts, transactions and item statuses, read as Omnibank's.

const RENEWAL_STATUSES = [402, 429, 430, 1010, 1100]

Item statuses the user must act on, through a connect session again: wrong credentials (402), an action on the bank's website (429), a password to change (430), the consent's strong authentication to renew (1010), a professional account to validate (1100).

Mapper::account()

public static function account(array $data): Account

Mapper::balances()

public static function balances(array $data): array

Returns

booked (balance), and instant (instant_balance, with what is pending) when Bridge gives it

Mapper::transaction()

public static function transaction(array $data, string $currency): ?BankTransaction

A booked transaction; null for a future or deleted one.

Mapper::consent()

public static function consent(mixed $status, ?string $info = null): Consent

What an item's status means for the consent; with no status code, its words (status_code_info).

Omnibank\Bridge\Action

AccountsAction class

final class AccountsAction implements ActionInterface, ApiAwareInterface AccountsAction.php:14

The user's accounts, every item (GET /v3/aggregation/accounts), every page.

AccountsAction::__construct()

public function __construct()

AccountsAction::supports()

public function supports(Request $request): bool

AccountsAction::execute()

public function execute(Request $request): void

BalancesAction class

final class BalancesAction implements ActionInterface, ApiAwareInterface BalancesAction.php:14

The account's balance as of its last refresh (GET /v3/aggregation/accounts/{id}), and its instant balance.

BalancesAction::__construct()

public function __construct()

BalancesAction::supports()

public function supports(Request $request): bool

BalancesAction::execute()

public function execute(Request $request): void

ConnectAction class

final class ConnectAction implements ActionInterface, ApiAwareInterface ConnectAction.php:26

A Bridge Connect session's page. The first time, a Bridge user is created (POST /v3/aggregation/users, its external_user_id the state's, or one made up) and kept in the state ("user_uuid", "external_user_id"); each time, a token (POST /v3/aggregation/authorization/token, kept: "access_token", "expires_at") opens a session (POST /v3/aggregation/connect-sessions) with the return URL as callback, the state's "user_email" when it has one, and - when the consent needs renewal and the state names the item ("item_id") - that item, for the user to authenticate again.

ConnectAction::__construct()

public function __construct(readonly ?string $callbackUrl = null, readonly ?string $countryCode = null)

ConnectAction::supports()

public function supports(Request $request): bool

ConnectAction::execute()

public function execute(Request $request): void

NotifyAction class

final class NotifyAction implements ActionInterface, ApiAwareInterface NotifyAction.php:24

A webhook, its signature checked (BridgeApi-Signature, see Api): the item.* events read as what they mean for the consent - the item's status one the user must act on (402, 429, 430, 1010, 1100) needs renewal, a deleted item is revoked, any other status is active. Other events (a test event, a user's) come back with consent NONE - they say nothing of it - to read from $raw. The connection is the item (content.item_id).

NotifyAction::__construct()

public function __construct()

NotifyAction::supports()

public function supports(Request $request): bool

NotifyAction::execute()

public function execute(Request $request): void

TransactionsAction class

final class TransactionsAction implements ActionInterface, ApiAwareInterface TransactionsAction.php:20

The account's booked transactions (GET /v3/aggregation/transactions, account_id, since and until the dates asked), every page (pagination.next_uri). Future and deleted transactions are left out, and those booked out of the dates asked.

TransactionsAction::__construct()

public function __construct()

TransactionsAction::supports()

public function supports(Request $request): bool

TransactionsAction::execute()

public function execute(Request $request): void