omnisense/omnibank API reference

Omnibank

Config class

final class Config extends ArrayObject Config.php:13

A gateway's configuration while its factory builds it: the options given, the factory's defaults under them, and the keys that must be filled.

Config::defaults()

public function defaults(array $defaults): self

Sets each key not set yet.

Config::validateNotEmpty()

public function validateNotEmpty(array $keys): void

Config::get()

public function get(string $key, mixed $default = null): mixed

Gateway class

final class Gateway implements GatewayInterface Gateway.php:18

A provider's actions behind one door: the first action supporting a request answers it.

Gateway::__construct()

public function __construct(readonly string $name, readonly string $title, readonly array $actions)

Gateway::getName()

public function getName(): string

Gateway::getTitle()

public function getTitle(): string

Gateway::supports()

public function supports(string $request): bool

Gateway::execute()

public function execute(Request\Request $request): Request\Request

Gateway::connect()

public function connect(Connection $connection, string $returnUrl): ConnectResult

Gateway::accounts()

public function accounts(Connection $connection): array

Gateway::balances()

public function balances(Connection $connection, Account $account): array

Gateway::transactions()

public function transactions(Connection $connection, Account $account, ?\DateTimeInterface $since = null, ?\DateTimeInterface $until = null): array

Gateway::transfer()

public function transfer(Connection $connection, Transfer $transfer): TransferResult

Gateway::notify()

public function notify(string $body, array $headers = []): Notification

GatewayFactory class

abstract class GatewayFactory implements GatewayFactoryInterface GatewayFactory.php:16

The Omnibus way: a provider's factory fills a Config - its name, title, the options it needs, its API client ("omnibank.api", a closure of the Config) and its actions ("omnibank.action.<name>") - and the gateway is those actions, the API handed to the ones that ask for it.

GatewayFactory::__construct()

public function __construct(protected readonly ?HttpClientInterface $http = null)

GatewayFactory::getName()

public function getName(): string

GatewayFactory::create()

public function create(array $options = []): GatewayInterface

GatewayFactory::createConfig()

public function createConfig(array $options = []): Config

GatewayFactoryInterface interface

interface GatewayFactoryInterface GatewayFactoryInterface.php:6

Builds a provider's gateway from its options (credentials, sandbox...).

GatewayFactoryInterface::getName()

public function getName(): string

The name gateways are configured with: "files", "qonto", "powens", "bridge".

..

GatewayFactoryInterface::create()

public function create(array $options = []): GatewayInterface

GatewayInterface interface

interface GatewayInterface GatewayInterface.php:23

One bank access, configured - statement files, a bank's own API (Qonto) or an aggregator (Powens, Bridge): the same questions for all of them. The application keeps the Connection (serialized) and hands it back on every call; connect() gives it back updated. Each typed method is a shortcut for execute() with its request; a provider that does not do something throws RequestNotSupportedException, and supports() says so beforehand.

GatewayInterface::getName()

public function getName(): string

GatewayInterface::getTitle()

public function getTitle(): string

GatewayInterface::supports()

public function supports(string $request): bool

GatewayInterface::execute()

public function execute(Request $request): Request

Returns

answered

Throws

Exception\RequestNotSupportedException

Throws

Exception\ProviderException

GatewayInterface::connect()

public function connect(Connection $connection, string $returnUrl): ConnectResult

Opens the access, or renews it: the hosted page to send the user to (null when there is nothing to do) and the connection with its new state (tokens, the provider's user) to keep.

GatewayInterface::accounts()

public function accounts(Connection $connection): array

GatewayInterface::balances()

public function balances(Connection $connection, Account $account): array

GatewayInterface::transactions()

public function transactions(Connection $connection, Account $account, ?\DateTimeInterface $since = null, ?\DateTimeInterface $until = null): array

The account's booked transactions, oldest first; their amount is negative when money leaves the account.

GatewayInterface::transfer()

public function transfer(Connection $connection, Transfer $transfer): TransferResult

GatewayInterface::notify()

public function notify(string $body, array $headers = []): Notification

What the provider is telling us (a webhook): checked against its signature, read as one event about one connection.

Throws

Exception\InvalidNotificationException when the signature does not hold

Registry class

final class Registry Registry.php:15

The application's bank accesses by name, each built once from its factory and options:

new Registry([new QontoGatewayFactory($http)], [ 'treasury' => ['factory' => 'qonto', 'options' => [...]], ]);

Registry::__construct()

public function __construct(iterable $factories, readonly array $config)

Registry::get()

public function get(string $name): GatewayInterface

Registry::has()

public function has(string $name): bool

Registry::options()

public function options(string $name): array

Returns

the options a gateway is configured with

Registry::create()

public function create(string $name, array $overrides = []): GatewayInterface

A gateway built afresh, its configured options with $overrides over them - keys typed in a back office, say. Not kept: get() still gives the configured one.

Registry::names()

public function names(): array

Returns

the configured gateways' names

Registry::all()

public function all(): array

Registry::factories()

public function factories(): array

Returns

the factories installed: what factory: may name

Omnibank\Action

ActionInterface interface

interface ActionInterface ActionInterface.php:8

One thing a provider does: answers the requests it supports.

ActionInterface::supports()

public function supports(Request $request): bool

ActionInterface::execute()

public function execute(Request $request): void

Sets the request's result, or throws Omnibank\Exception\ProviderException.

ApiAwareInterface interface

interface ApiAwareInterface ApiAwareInterface.php:6

An action that talks to the provider through the gateway's API client.

ApiAwareInterface::setApi()

public function setApi(object $api): void

ApiAwareTrait trait

trait ApiAwareTrait ApiAwareTrait.php:10

ApiAwareTrait::setApi()

public function setApi(object $api): void

Omnibank\Bridge\Symfony

OmnibankBundle class

final class OmnibankBundle extends AbstractBundle OmnibankBundle.php:36

Omnibank in a Symfony application: the provider packages installed (omnibank/files, omnibank/qonto, omnibank/powens, omnibank/bridge) registered, the application's bank accesses built from configuration, Omnibank\Registry autowired, and each gateway injectable by its name:

omnibank: gateways: statements: { factory: files, options: { debtor_name: 'Nakaya SAS' } } treasury: { factory: qonto, options: { login: '%env(QONTO_LOGIN)%', secret_key: '%env(QONTO_SECRET_KEY)%' } }

public function __construct(GatewayInterface $treasury) }

An application's own factories (a GatewayFactoryInterface) are registered too, autoconfigured.

OmnibankBundle::configure()

public function configure(DefinitionConfigurator $definition): void

OmnibankBundle::loadExtension()

public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void

Omnibank\Exception

InvalidConfigException class

final class InvalidConfigException extends LogicException implements OmnibankException InvalidConfigException.php:6

A gateway misconfigured: a credential missing, an unknown factory.

InvalidNotificationException class

final class InvalidNotificationException extends ProviderException InvalidNotificationException.php:6

A webhook that is not the provider's: its signature does not hold, or it is too old.

OmnibankException interface

interface OmnibankException extends Throwable OmnibankException.php:6

Every exception Omnibank throws.

ProviderException class

class ProviderException extends RuntimeException implements OmnibankException ProviderException.php:6

The provider refused: wrong credentials, an unknown account, a file it cannot read.

public readonly string $provider

public readonly ?string $providerCode

The provider's own error code, when it gave one

ProviderException::__construct()

public function __construct(public readonly string $provider, string $message, public readonly ?string $providerCode = null, ?\Throwable $previous = null)

RequestNotSupportedException class

final class RequestNotSupportedException extends LogicException implements OmnibankException RequestNotSupportedException.php:8

The provider does not do that (no transfers, no webhooks...).

RequestNotSupportedException::for()

public static function for(Request $request, string $gateway): self

UnavailableException class

final class UnavailableException extends ProviderException UnavailableException.php:10

The provider could not be reached or failed on its side (network, timeout, 5xx, rate limit): nothing is known, which is not the same as nothing there. Never read it as "no accounts" or "no transactions"; try again later.

Omnibank\Http

Redaction class

final class Redaction Redaction.php:22

What a failed call may carry of its credentials, taken out before the failure leaves the package: an HTTP client's exception quotes the URL called (a key in its query, a password in its user part), and every exception's trace keeps the arguments of the calls under it (the request options, headers and query with the key) unless PHP runs with zend.exception_ignore_args.

copy() gives the previous exception to wrap instead of the client's own: the same class and code, its message with the key's parameters, the user part and every secret value replaced by ***, its trace without arguments, its own previous copied the same way. Properties of the client's class beyond those of \Exception are not copied (a Symfony HttpException's response, a PSR-18 exception's request: their URL holds the key). withoutArguments() takes the arguments out of the trace of the exception thrown in its place.

const MASK = '***'

Redaction::secrets()

public static function secrets(string $url, array $options = []): array

The secrets a request carries: the values of its query parameters, headers and body fields named as credentials (key, token, secret, password, signature, auth...), a bearer token, a basic password, the URL's user part.

$options

the HTTP client's options

Redaction::sensitive()

public static function sensitive(string $name): bool

Whether a parameter, header or field of this name holds a credential.

Redaction::text()

public static function text(string $text, array $secrets = []): string

A text without credentials: in every address, the user part and the parameters named as credentials masked (api_key=***); then every secret given, raw or URL-encoded, masked wherever it stands.

Redaction::copy()

public static function copy(\Throwable $failure, array $secrets = []): \Throwable

A copy of a failure to wrap in its place: its class, code, file and line, its message through text(), its trace without arguments, its previous copied the same way.

Redaction::withoutArguments()

public static function withoutArguments(\Throwable $failure): \Throwable

The failure given, the arguments out of its trace (and out of its previous ones'), as zend.exception_ignore_args would have left it.

Omnibank\Model

Account class

final readonly class Account Account.php:10

A bank account as the provider knows it. $id is the provider's (what balances() and transactions() are asked with); $raw keeps the provider's whole answer, for what this model leaves out.

public string $id

public ?string $iban

public ?string $bic

public string $name

public string $currency

public ?string $type

The provider's word for it: "checking", "savings", "card".

..

public array $raw

Account::__construct()

public function __construct(public string $id, public ?string $iban, public ?string $bic, public string $name, public string $currency, public ?string $type, public array $raw = [])

Balance class

final readonly class Balance Balance.php:10

What an account holds at a moment. $type says which balance: "booked" (what has been entered), "available" (what can be spent), "expected" (with what is coming), or the provider's own word.

public Money $amount

public \DateTimeImmutable $at

public string $type

Balance::__construct()

public function __construct(public Money $amount, public \DateTimeImmutable $at, public string $type = 'booked')

BankTransaction class

final readonly class BankTransaction BankTransaction.php:10

One booked line of an account. $amount is negative when money leaves the account. $id is stable - the bank's reference, or a hash of the line when it has none - so the same line read twice is the same transaction.

public string $id

public \DateTimeImmutable $bookedOn

public ?\DateTimeImmutable $valueOn

public Money $amount

public string $label

The bank's label for the line, as it shows on the statement.

public ?string $counterpartyName

public ?string $counterpartyIban

public ?string $reference

What the payer wrote: the remittance information, an end-to-end id.

public array $raw

BankTransaction::__construct()

public function __construct(public string $id, public \DateTimeImmutable $bookedOn, public ?\DateTimeImmutable $valueOn, public Money $amount, public string $label, public ?string $counterpartyName, public ?string $counterpartyIban, public ?string $reference, public array $raw = [])

BankTransaction::isDebit()

public function isDebit(): bool

ConnectResult class

final readonly class ConnectResult ConnectResult.php:10

What connect() gives back: the page to send the user to (a provider's webview, a connect session) or null when there is nothing to do, and the connection to keep - its state may have changed (a user created, a token).

public ?string $url

public Connection $connection

ConnectResult::__construct()

public function __construct(public ?string $url, public Connection $connection)

ConnectResult::isRedirect()

public function isRedirect(): bool

Connection class

final readonly class Connection Connection.php:11

What the application keeps for one bank access and hands back on every call: the provider's state (its user, its tokens, the statement files) and the consent. Stored serialized - serialize() or toArray()/fromArray() for JSON; it holds credentials (tokens), so keep it as you keep secrets.

public array $state

public Consent $consent

Connection::__construct()

public function __construct(public array $state = [], public Consent $consent = new Consent(ConsentStatus::NONE))

Connection::withState()

public function withState(array $state): self

The same connection, its state replaced by $state.

Connection::withConsent()

public function withConsent(Consent $consent): self

Connection::get()

public function get(string $key, mixed $default = null): mixed

A key of the state, or $default.

Connection::toArray()

public function toArray(): array

Connection::fromArray()

public static function fromArray(array $data): self

Consent class

final readonly class Consent Consent.php:6

The user's consent: where it stands, and until when when the provider says.

public ConsentStatus $status

public ?\DateTimeImmutable $expiresAt

Consent::__construct()

public function __construct(public ConsentStatus $status, public ?\DateTimeImmutable $expiresAt = null)

Consent::none()

public static function none(): self

Consent::active()

public static function active(?\DateTimeImmutable $expiresAt = null): self

Consent::needsRenewal()

public static function needsRenewal(?\DateTimeImmutable $expiresAt = null): self

Consent::revoked()

public static function revoked(): self

Consent::isActive()

public function isActive(?\DateTimeInterface $now = null): bool

Active, and not past its expiry date (at $now, or now).

Consent::toArray()

public function toArray(): array

Consent::fromArray()

public static function fromArray(array $data): self

ConsentStatus enum

enum ConsentStatus ConsentStatus.php:6

Where the user's consent to reach the accounts stands, whatever the provider calls it.

case ACTIVE = 'active'

The accounts can be read.

case NEEDS_RENEWAL = 'needs_renewal'

The user must go through the provider's page again (expired consent, SCA, new password).

case REVOKED = 'revoked'

The user or the bank withdrew it.

case NONE = 'none'

Never given.

Money class

final readonly class Money Money.php:9

An amount in a currency's minor units (cents), signed: -1250 EUR is 12,50 € gone out of the account.

public string $currency

public int $amount

Money::__construct()

public function __construct(public int $amount, string $currency)

Money::of()

public static function of(int $amount, string $currency): self

Money::isNegative()

public function isNegative(): bool

Money::isZero()

public function isZero(): bool

Money::negate()

public function negate(): self

Money::abs()

public function abs(): self

Money::equals()

public function equals(self $other): bool

Money::decimal()

public function decimal(): string

In major units, as a bank file or a decimal API expects ("-12.50"); yen and the like have none.

Money::fromDecimal()

public static function fromDecimal(string|int|float $decimal, string $currency): self

From a decimal ("12.50", "-0.5", 12.5), to minor units. A string is read digit by digit, never through a float, so "1234.56" is exactly 123456.

Money::minorDigits()

public static function minorDigits(string $currency): int

How many minor digits a currency has: 2 for most, 0 for JPY, KRW..., 3 for BHD, KWD.

..

Money::__toString()

public function __toString(): string

Notification class

final readonly class Notification Notification.php:11

What a provider is telling us, checked: one event about one connection.

$type is the provider's own name for it ("CONNECTION_SYNCED", "item.refreshed"); $consent what it means for the user's consent; $connectionId the provider's connection (an item, a Powens connection).

public string $type

public ?string $connectionId

public Consent $consent

public array $raw

Notification::__construct()

public function __construct(public string $type, public ?string $connectionId, public Consent $consent, public array $raw)

Transfer class

final readonly class Transfer Transfer.php:11

A SEPA credit transfer to make: from the debtor's account to the creditor's. $amount is what is sent, positive. $reference is the remittance information the creditor sees (140 characters at most); $endToEndId travels with the money to the creditor's bank.

public string $debtorIban

public string $creditorName

public string $creditorIban

public ?string $creditorBic

public Money $amount

public string $reference

public ?string $endToEndId

public ?\DateTimeImmutable $executionDate

When the bank should execute it; today when null.

Transfer::__construct()

public function __construct(public string $debtorIban, public string $creditorName, public string $creditorIban, public ?string $creditorBic, public Money $amount, public string $reference, public ?string $endToEndId = null, public ?\DateTimeImmutable $executionDate = null)

TransferResult class

final readonly class TransferResult TransferResult.php:10

What became of a transfer: its id at the provider (or the message id of the file), the provider's status for it, and - when the transfer is a file to hand the bank (a pain.001) - the file's content and name.

public string $id

public string $status

"generated" (a file to upload), or the provider's own: "pending", "executed", "rejected".

..

public ?string $file

public ?string $fileName

TransferResult::__construct()

public function __construct(public string $id, public string $status, public ?string $file = null, public ?string $fileName = null)

Omnibank\Request

Connect class

final class Connect extends Request Connect.php:13

Open the access, or renew its consent. Result: a ConnectResult - the page to send the user to (null when there is nothing to do) and the connection with its new state.

public readonly Connection $connection

public readonly string $returnUrl

Connect::__construct()

public function __construct(public readonly Connection $connection, public readonly string $returnUrl)

Connect::getConnectResult()

public function getConnectResult(): ?ConnectResult

FetchAccounts class

final class FetchAccounts extends Request FetchAccounts.php:9

The accounts the connection reaches. Result: list<Account>.

public readonly Connection $connection

FetchAccounts::__construct()

public function __construct(public readonly Connection $connection)

FetchAccounts::getAccounts()

public function getAccounts(): array

FetchBalances class

final class FetchBalances extends Request FetchBalances.php:10

An account's balances as the provider knows them. Result: list<Balance>.

public readonly Connection $connection

public readonly Account $account

FetchBalances::__construct()

public function __construct(public readonly Connection $connection, public readonly Account $account)

FetchBalances::getBalances()

public function getBalances(): array

FetchTransactions class

final class FetchTransactions extends Request FetchTransactions.php:13

An account's booked transactions, between two dates when given (both included, on the booking date). Result: list<BankTransaction>, oldest first.

public readonly Connection $connection

public readonly Account $account

public readonly ?\DateTimeInterface $since

public readonly ?\DateTimeInterface $until

FetchTransactions::__construct()

public function __construct(public readonly Connection $connection, public readonly Account $account, public readonly ?\DateTimeInterface $since = null, public readonly ?\DateTimeInterface $until = null)

FetchTransactions::covers()

public function covers(\DateTimeInterface $bookedOn): bool

Whether a booking date falls between since and until, days compared.

FetchTransactions::getTransactions()

public function getTransactions(): array

Notify class

final class Notify extends Request Notify.php:12

What the provider sent to the webhook: the raw body and the request's headers, for the signature. Result: the Notification, or InvalidNotificationException when the signature does not hold.

public readonly string $body

public readonly array $headers

Notify::__construct()

public function __construct(public readonly string $body, public readonly array $headers = [])

Notify::header()

public function header(string $name): ?string

A header, whatever the case it came in.

Notify::getNotification()

public function getNotification(): ?Notification

Request class

abstract class Request Request.php:9

A question put to a gateway. The action that supports it answers by setting the result; the gateway hands the request back.

Request::setResult()

public function setResult(mixed $result): void

Request::getResult()

public function getResult(): mixed

Request::isAnswered()

public function isAnswered(): bool

Transfer class

final class Transfer extends Request Transfer.php:13

Send money: a SEPA credit transfer. Result: a TransferResult - what the provider made of it, and the file to hand the bank when it is one.

public readonly Connection $connection

public readonly TransferModel $transfer

Transfer::__construct()

public function __construct(public readonly Connection $connection, public readonly TransferModel $transfer)

Transfer::getTransferResult()

public function getTransferResult(): ?TransferResult