Operational guidance for running installed connectors — how often they poll, how to find their schedules, how to monitor health, and how to recover when something drifts. For what each connector actually does, see Capabilities.
Polling cadence#
When installing a connector — on Formance Console or via the API — you can configure a pollingPeriod that defaults to 30 minutes if not specified. It drives every periodic capability the connector exposes — Accounts, Balances, External Accounts, Payments, Orders, Conversions, plus the poll loop on in-flight Transfer / Payout statuses.
Each connector declares a minimum polling period the platform enforces at install time. The common floor is 20 minutes (Stripe, Bankingcircle, Routable, Bitstamp, Mangopay, …); a few connectors with slower-moving data or stricter upstream rate limits raise the floor higher. Submitting a pollingPeriod below the floor is rejected with a clear validation error before the connector is installed — see the per-connector page for the exact value (look for the pollingPeriod row in the Configuration fields table).
Monitoring connector schedules#
To check when a connector last pulled data, use the Connector Schedule APIs.
Finding the schedule ID#
Each connector has schedules that are automatically generated when the connector is installed. The schedule ID follows this format:
For example: stack123-abc-FETCH_ACCOUNTS
To find the schedule IDs for your connectors, use the List All Connector Schedules endpoint.
Checking last pull time#
Once you have the schedule ID, call the List Connector Schedule Instances endpoint with the schedule ID to see the history of data pulls, including the most recent one.
This is useful for:
- Debugging synchronization issues
- Monitoring connector health
- Verifying data freshness
Connector reliability#
Health checks and auto-pause#
The platform runs a background health check per installed connector that looks at the recent error history of its fetch schedules and pauses any schedule that has accumulated more than the error threshold of consecutive failures. By default the check runs every 12 hours and the threshold is 10 consecutive errors. Only fetch schedules are eligible for auto-pause (accounts, payments, external accounts, balances, orders, conversions, others) — payout and transfer workflows are never auto-paused.
To resume a paused schedule, update the connector configuration via v3UpdateConnectorConfig. The next health check ignores instances created before the config update, so once the underlying cause is fixed the error count restarts at zero.
Self-hosted operators can tune the cadence and threshold on the payments run-worker command:
Payout rate limiting#
Some payment service providers cap the rate at which payouts and transfers can be submitted. Connector plugins that opt in via the PluginWithPayoutThrottle interface declare a maximum payouts-per-second; when set, the platform routes CreatePayout and CreateTransfer workflows for that connector through a dedicated Temporal task queue whose activity rate is throttled to that value.
This is a plugin-level guarantee, not an installation-level setting — readers don't tune it. The Routable EE connector is the first to use it (currently 1.5 payouts/s). Other connectors fall back to the default unthrottled task queue.
Webhook delivery to uninstalled connectors#
Webhooks targeting a connector that has been uninstalled now return HTTP 404 Not Found instead of a 5xx error. PSPs that interpret 5xx as "transient — retry later" can use the 404 as a signal to stop retrying.
Payment reference enrichment#
Connector plugins may enrich Payment metadata with PSP-specific reference fields they extract from upstream payloads — end-to-end IDs, mandate IDs, clearing-system references, creditor reference info, and similar. These land under the com.formance.connectors.<provider>. metadata namespace on Payments returned from the list payments endpoint. The Banking Bridge connector applies this pattern most extensively.
Operator commands#
Self-hosted operators have a payments recreate-schedules CLI subcommand that recreates missing Temporal schedules for all currently-active connectors. Useful after Temporal data loss, a schedule-namespace migration, or when schedules have drifted out of sync with the stored connector state. The command is fully idempotent — existing schedules are silently skipped.
It connects to the same database and Temporal namespace as run-worker and walks each connector's stored task tree to rebuild its periodic root tasks.