Powens

The Powens connector links Formance to Powens' European bank-aggregation platform. Once installed, it lets your stack drive the Open Banking PSU flow across Powens' supported markets — create a Payment Service User, forward them to Powens, hand them a Powens Webview session, and once they've authenticated their bank, sync the resulting accounts, balances, and transactions back through Connectivity.

The connector first ships in Payments 3.2.0.

Prerequisites#

You need a Powens domain (*.biapi.pro) and a clientID + clientSecret + configurationToken triplet dedicated to Formance. Powens authenticates each PSU with a user-scoped permanent access token derived from the configurationToken at PSU registration time; the connector mints and stores the token per PSU automatically.

maxConnectionsPerLink caps how many bank connections a single Webview session can produce — Powens lets you raise the cap; pick a value that matches the depth of integration you want per PSU.

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 you (e.g. acme-sandbox.biapi.pro or acme.biapi.pro). endpoint is the API root for that domain, typically https://<domain>/2.0.

Capabilities#

• FETCH_ACCOUNTS — depository, credit, and loan accounts attached to each PSU's connections.
• FETCH_BALANCES — available + booked balance per account.
• FETCH_EXTERNAL_ACCOUNTS — counterparty accounts identified by Powens when present.
• FETCH_PAYMENTS — transactions, paginated via Powens' limit + offset.
• CREATE_WEBHOOKS + TRANSLATE_WEBHOOKS — at install time the connector subscribes to the webhook topics Powens supports (USER_SYNCED, CONNECTION_SYNCED, CONNECTION_DELETED, …) so refresh events flow back in real time.

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

Linking a user#

Powens' authentication ceremony runs through Powens Webview. The Connectivity surface is:

1. Create a PSU — v3CreatePaymentServiceUser. Returns a PSU ID.
2. Forward the PSU to Powens — v3ForwardPaymentServiceUserToProvider. The connector 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 public https://webview.powens.com/... URL plus an attemptID.
4. Frontend redirects the user to the Webview URL. They pick their bank, complete strong customer authentication, and Powens redirects them back to your clientRedirectURL.
5. Powens posts a USER_SYNCED webhook. The connector ingests it and starts syncing the freshly-linked connections.

The full step-by-step walkthrough is on the Open Banking Getting Started guide.

Redirect URL requirements#

• Must be HTTPS in production.
• Must be registered under your Powens client's allowed redirect URIs (via the Powens admin).
• Mobile apps must follow Powens' Webview browser-integration guide — in-app webviews are not supported by every bank in the Powens network.

Asset model#

Powens is multi-currency. The connector formats balances and payments to UMN with the precision per ISO 4217. Amounts are decimal strings; the connector applies major-to-minor scaling before emission.

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#

Powens-specific fields land 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 the connector created) and expires_in (the access-token's 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#

Powens uses limit + offset pagination. The connector advances the watermark per PSU/account in the platform-managed State; restarts resume from the last committed offset.

Known gaps#

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