omnibank/powens Référence de l’API

Omnibank\Powens

Api class

final class Api Api.php:24

Powens' API 2.0 on the client's domain (https://<x>-sandbox.biapi.pro/2.0/), a user's calls with the user's permanent token (Bearer), and its Webview.

Webhooks: Powens signs them with the webhook secret of the console. This client reads the signature as Powens documents it - BI-Signature: base64 of the HMAC-SHA256 of "POST.<webhook path>.<BI-Signature-Date>.<body>", compared exactly - and refuses a webhook whose BI-Signature-Date is more than the tolerance away from now (a webhook captured and sent again). Not yet checked against a real sandbox webhook.

const WEBVIEW = 'https://webview.powens.com'

const WEBHOOK_TOLERANCE = 300

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

public readonly string $clientId

Api::__construct()

public function __construct(readonly HttpClientInterface $http, readonly string $domain, public readonly string $clientId, readonly string $clientSecret, readonly ?string $webhookSecret = null, readonly ?string $webhookUrl = null, readonly string $webview = self::WEBVIEW, readonly ?string $language = null, readonly int $timeout = 30, readonly int $webhookTolerance = self::WEBHOOK_TOLERANCE)

Api::token()

public static function token(Connection $connection): string

The user's permanent token, from the connection's state: connect() puts it there.

Api::createUser()

public function createUser(): array

A new Powens user: its permanent token and its id.

@return array{auth_token: string, id_user: int|string|null}

Api::temporaryCode()

public function temporaryCode(string $token): string

A temporary code for the user's token: what the Webview is opened with.

Api::webviewUrl()

public function webviewUrl(string $code, string $redirectUri, ?string $connectionId = null): string

The Webview's page: connect a bank, or - with a connection id - renew that connection.

Api::call()

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

$body

JSON

Throws

ProviderException when Powens refuses (4xx)

Throws

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

Api::verify()

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

Throws

InvalidNotificationException

Api::signatures()

public static function signatures(string $body, string $secret, ?string $date = null, ?string $webhookUrl = null): array

The signature Powens sends for a body (BI-Signature): the base64 of the HMAC-SHA256 of "POST.<webhook path>.<date>.<body>". A list (of one, when the date and the URL are given) for the callers that took it so; without a date or a URL there is nothing to sign.

Mapper class

final class Mapper Mapper.php:12

Powens' accounts, transactions and connection states, read as Omnibank's.

const RENEWAL_STATES = ['SCARequired', 'webauthRequired', 'decoupled', 'additionalInformationNeeded', 'actionNeeded', 'wrongpass', 'passwordExpired']

Connection states the user must act on: through the Webview again (reconnect).

Mapper::account()

public static function account(array $data): Account

Mapper::balances()

public static function balances(array $data, string $currency): array

Returns

booked (balance), and expected (balance with what is coming) when Powens knows what is coming

Mapper::transaction()

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

A booked transaction; null for one still coming or deleted.

Mapper::consent()

public static function consent(array $connection): Consent

What a connection's state means for the consent: null is fine, a state the user must act on needs renewal.

PowensGatewayFactory class

final class PowensGatewayFactory extends GatewayFactory PowensGatewayFactory.php:32

Powens (ex Budget Insight): the user connects their banks in Powens' Webview; accounts, balances and transactions are read with the user's permanent token, kept in the connection's state; CONNECTION_SYNCED webhooks say when the data is fresh or the consent must be renewed. No transfers in this version.

options: domain: 'nakaya-sandbox.biapi.pro' # the client's domain in the Powens console client_id: '%env(POWENS_CLIENT_ID)%' client_secret: '%env(POWENS_CLIENT_SECRET)%' redirect_uri: 'https://app.example/bank/back' # when connect() is given no return URL; whitelisted in the console webhook_secret: '%env(POWENS_WEBHOOK_SECRET)%' # for notify() webhook_url: 'https://app.example/bank/webhook' # the URL registered, its path signed; for notify() webhook_tolerance: 300 # seconds a webhook's BI-Signature-Date may be from now webview: 'https://webview.powens.com' language: null # "fr", "en"...: the Webview's

Options

Omnibank\Powens\Action

AccountsAction class

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

The user's accounts, every bank connected (GET /users/me/accounts).

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 sync (GET /users/me/accounts/{id}), and with what is coming.

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:24

The Webview page the user connects a bank on. The first time, a Powens user is created (POST /auth/init) and its permanent token kept in the connection's state ("auth_token", "user_id"); each time, a temporary code (GET /auth/token/code) opens the Webview. When the consent needs renewal and the state names the connection ("connection_id" - the Webview hands it back on the return URL, the webhook gives it too), the page is the reconnect one for that connection.

ConnectAction::__construct()

public function __construct(readonly ?string $redirectUri = 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 (BI-Signature, see Api). Powens sends one kind of event per registered URL and does not name it in the body: a body with a "connection" is read as CONNECTION_SYNCED, its connection's state as the consent (SCARequired, webauthRequired, decoupled, wrongpass... need renewal). Any other body is handed back as "UNKNOWN", consent NONE - it says nothing of it - to read from $raw.

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 /users/me/accounts/{id}/transactions, min_date and max_date the dates asked), every page: the next link Powens gives (_links.next.href), else the next offset while pages come full.

Transactions still coming, and deleted ones, are left out.

TransactionsAction::__construct()

public function __construct()

TransactionsAction::supports()

public function supports(Request $request): bool

TransactionsAction::execute()

public function execute(Request $request): void