The Generic Connector lets Reconciliation use balance data from a provider that Formance does not support natively. You run a small integration service that speaks to the provider and implements the Generic Connector contract; Formance Payments ingests its accounts, balances, and transactions.
1. Build the integration service#
Your service is responsible for:
- authenticating with the provider;
- translating provider accounts and balances into the Generic Connector format;
- exposing the required HTTP endpoints;
- handling provider pagination, rate limits, and retries;
- preserving stable account identifiers across polling cycles.
Follow How the Generic Connector works for the wire contract and Generic Connector Getting Started for installation.
2. Choose the polling period#
Payments obtains new balance observations by polling your service. Select a period that is short enough for the reconciliation objective and acceptable for the provider's rate limits.
Reconciliation can only use external balance history that Payments has ingested. A historical read outside the available balance window can return no balance. Monitor connector health and validate the intended timestamps before relying on a scheduled control.
3. Group the provider accounts#
Create a cash pool containing the accounts that represent one reconciliation position. Use a static pool for a fixed, explicitly managed set or a dynamic pool when accounts should join automatically based on connector, asset, type, or metadata.
Keep each pool aligned with one clear financial meaning. Mixing unrelated settlement or safeguarding accounts can produce a total that balances while hiding a discrepancy inside the group.
4. Create a continuous control#
Use the pool in one of these control templates:
ledger_vs_pool_driftwhen the Ledger side and external cash use a signed backing relationship;source_paritywhen two balance sources should report the same amount.
Start with an on-demand rule and explicit historical timestamps. Confirm the pool membership, sign convention, per-asset balances, and tolerance in the first evaluation's evidence. Only then enable a cron schedule.
If the provider settles later than Ledger, use separate source timestamps instead of an unnecessarily broad tolerance. sourcePITs records that timing decision on every evaluation and makes the comparison explainable later.
Operational responsibilities#
The Generic Connector extends provider coverage, but your integration remains part of the control environment. Monitor:
- successful polling and freshness of the latest balance;
- mapping changes after provider API upgrades;
- account membership in dynamic pools;
- time zones and settlement cutoffs;
- provider corrections or backfilled history.
Source or connector failures produce an ERROR evaluation and a distinct engine.error alert. Route those alerts to the integration team; they indicate that the financial control could not run, not that a balance discrepancy was confirmed.