Powens

The Powens connector links Formance to Powens' European bank-aggregation platform. It drives the Open Banking PSU flow across Powens' markets: create a Payment Service User, forward them to Powens, hand them a Powens Webview session, and sync the resulting accounts, balances, and transactions back through Connectivity. Available from Payments 3.2.0.

Prerequisites#

You need a Powens domain (*.biapi.pro) and a clientID + clientSecret + configurationToken triplet. Each PSU is authenticated by a user-scoped permanent access token derived from the configurationToken at registration; the connector mints and stores the token per PSU automatically.

maxConnectionsPerLink caps the number of bank connections per Webview session — Powens lets you raise the cap; pick the depth of integration you want.

Installation#

curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/powens \
  -H "Content-Type: application/json" \
  -d @config.json

Configuration fields#

domain is the tenant-scoped subdomain Powens issued (e.g. acme.biapi.pro). endpoint is the API root for that domain, typically https://<domain>/2.0.

Capabilities#

• FETCH_ACCOUNTS — depository, credit, and loan accounts per PSU connection.
• FETCH_BALANCES — available + booked balance per account.
• FETCH_EXTERNAL_ACCOUNTS — counterparty accounts when Powens identifies them.
• FETCH_PAYMENTS — transactions, paginated via limit + offset.
• CREATE_WEBHOOKS + TRANSLATE_WEBHOOKS — subscribes to USER_SYNCED, CONNECTION_SYNCED, CONNECTION_DELETED, ….

The connector doesn't initiate transfers or payouts — Powens' outbound product is not wired here.

Account model#

Every Connectivity internal account is one Powens BankAccount from a linked connection. The reference is the account ID stringified; name is the original_name; defaultAsset is currency.id at the precision Powens publishes. Accounts are PSU-scoped — psuID and openBankingConnectionID track the link. When Powens reports an error on the account, it lands in metadata. EXTERNAL accounts are emitted when Powens identifies them. See Accounts for the cross-connector model.

Linking a user#

Powens' auth ceremony runs through Powens Webview:

1. Create a PSU — v3CreatePaymentServiceUser returns a PSU ID.
2. Forward to Powens — v3ForwardPaymentServiceUserToProvider creates a Powens user with the configurationToken, mints a permanent access token, and stores both as PSU metadata.
3. Create a Webview session — v3CreateLinkForPaymentServiceUser returns a https://webview.powens.com/... URL + attemptID.
4. Frontend redirect — the user picks a bank, completes SCA, and lands on your clientRedirectURL.
5. USER_SYNCED webhook — the connector ingests it and starts syncing the linked connections.

Step-by-step walkthrough on the Open Banking Getting Started guide.

Redirect URL requirements#

• HTTPS in production.
• Registered under the Powens client's allowed redirect URIs.
• Mobile apps must follow Powens' Webview browser-integration guide — in-app webviews aren't supported by every bank in the network.

Asset model#

Multi-currency, formatted to UMN at ISO 4217 precision. Amounts arrive as decimal strings; the connector applies major-to-minor scaling.

Status mapping#

Powens transactions are non-stateful; they appear after they post:

When a PENDING transaction matures, Powens replaces the provisional ID with a permanent one and the connector swaps the reference.

Metadata keys#

Under com.powens.spec/:

• Account: account_id, iban, bic, account_number, name, type (checking / savings / card / loan / …), usage (PRIV / ORGA).
• External account: counterparty_id, account_number, iban, name.
• Payment: transaction_id, category_id, description, original_wording, simplified_wording, last_update, type (transfer / card / bank / …).

PSU-level metadata carries user_id (the Powens user) and expires_in (token remaining lifetime).

Workflow tree#

FetchAccounts (periodic) — per PSU
  ├── FetchBalances (FromPayload — no extra API call)
  └── FetchPayments (periodic) — per PSU/account, offset/limit cursor
FetchExternalAccounts (periodic)
CreateWebhooks — provisioned at install

Pagination and recovery#

limit + offset. Watermarks persist per PSU/account in platform-managed State; restarts resume from the last committed offset.

Known gaps#

• Outbound initiation is not wired.
• Investment accounts surface as accounts but their positions don't — only depository balances and transactions land.
• Consent expiry: connections expire after the PSD2 SCA window. Powens emits CONNECTION_PENDING_DISCONNECT; the connector translates it to UserConnectionPendingDisconnect — trigger a fresh Webview via v3UpdateLinkForPaymentServiceUser to renew.