The Qonto connector polls a Qonto organisation and surfaces business bank accounts, balances, beneficiaries, and transactions. It is read-only: Qonto's outbound transfer and webhook surfaces require three-legged OAuth2, which the framework does not drive.
Prerequisites#
You need a Qonto organisation and an API key pair. Qonto authenticates with login:secret-key in the Authorization header; staging additionally requires a stagingToken header.
Make sure to create an API key dedicated to Formance. Doing so will improve your auditability and security and will allow you to revoke access to Formance at any time if needed.
Installation#
curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/qonto \
-H "Content-Type: application/json" \
-d @config.jsonConfiguration fields#
| Field | Type | Required | Default |
|---|---|---|---|
apiKey | string | Yes | |
clientID | string | Yes | |
endpoint | string | Yes | |
pageSize | integer | No | 25 |
pollingPeriod | string | No | 30m |
stagingToken | string | No |
Production: https://thirdparty.qonto.com. Staging: https://thirdparty.staging.qonto.co with a stagingToken.
Capabilities#
FETCH_ACCOUNTS— bank accounts viaGET /v2/organizations.FETCH_BALANCES— authorized + balance per account.FETCH_EXTERNAL_ACCOUNTS— beneficiaries.FETCH_PAYMENTS—GET /v2/transactions, classified per direction.
Qonto exposes outbound transfer initiation and webhooks upstream, but both require three-legged OAuth2 that the framework doesn't yet drive — the connector advertises only the read capabilities.
Account model#
Every Connectivity internal account is one Qonto bank account under the organisation. GET /v2/organizations returns the whole tree at once — there's no per-account endpoint. The reference is the bank-account ID; name is the account name; defaultAsset is EUR/2 (Qonto is EUR-only). EXTERNAL accounts come from Qonto beneficiaries. See Accounts for the cross-connector model.
Asset model#
EUR-only — every balance and payment is EUR/2. Amounts are already in minor units.
Status mapping#
Qonto transaction status | Payment status |
|---|---|
pending | PENDING |
completed | SUCCEEDED |
declined | FAILED |
reversed | CANCELLED |
| anything else | UNKNOWN |
Metadata keys#
Under com.qonto.spec/:
- Account:
iban,bic,currency,organization_slug. - External account:
beneficiary_id,iban,bic,bank_name,trusted(boolean). - Payment:
transaction_id,operation_type(card/transfer/direct_debit/cheque/swift_income/ …),side(credit/debit),reference,note.
Workflow tree#
FetchAccounts (periodic)
├── FetchBalances (FromPayload — no extra API call)
└── FetchPayments (periodic) — per account
FetchExternalAccounts (periodic)Pagination and recovery#
1-indexed current_page + per_page (max 100). The connector persists the watermark per stream in platform-managed State.
Known gaps#
- Outbound initiation is not implemented — Qonto's
CreateTransferAPI requires 3-legged OAuth2. - Webhooks are not implemented for the same reason.
- Multi-organisation tenants: one connector install covers one organisation.