Skip to main content
Understanding the core concepts of Formance Reconciliation will help you effectively implement and use the service to maintain financial accuracy across your payment systems.

​
Policies

A reconciliation policy defines which ledger accounts to compare with which cash pools. Each policy contains four required fields:

​
Policy Components

​
name
string
required
A human-readable identifier for the policy (e.g., “Stripe Settlement Reconciliation”)
​
ledgerName
string
required
The name of the Formance Ledger instance to reconcile against
​
ledgerQuery
object
required
Query parameters that define which ledger accounts to include in the reconciliation
​
paymentsPoolID
string
required
The UUID of the cash pool to reconcile against the ledger accounts

​
Reconciliation

A reconciliation compares balances between your Formance Ledger and a cash pool at specific timestamps. You provide:
  • reconciledAtLedger - timestamp for ledger balance retrieval (must be in the past)
  • reconciledAtPayments - timestamp for cash pool balance retrieval (must be in the past)
The reconciliation stores the results with status OK or NOT_OK, along with ledgerBalances, paymentsBalances, and driftBalances for any discrepancies.

​
Drift Detection

When balances don’t match between systems, the service calculates drift - the exact difference stored in driftBalances. All drift amounts are calculated as absolute values and stored per asset.

​
Reconciliation Process

The reconciliation process is synchronous, meaning that when you call the reconcile endpoint, it will not return until the reconciliation is complete. Once the reconciliation job finishes:
  • The reconciliation will be immediately available through the API list endpoints
  • The status will indicate whether any drift was detected
Since the process is synchronous, there is no “in progress” status - reconciliations are only visible in the API after they have completed.

​
Troubleshooting

​
Why is my reconciliation returning a balance of 0?

If your reconciliation policy is unexpectedly returning a balance of 0 for payment accounts, it may be related to the polling period set for your connector.

​
Understanding the polling period

The polling period determines how often your connector fetches updated balance information from the payment provider. If set to 1 hour, for example, balances are updated hourly.

​
How polling affects reconciliation

When you run a reconciliation between balance updates, the system may return a balance of 0. This is because the exact balance on the third-party side at that specific time is unknown. Example:
  • Balance updated at 3:14 PM: 100 USD
  • Next balance update scheduled for 4:14 PM
  • If you reconcile at 3:30 PM, the balance may show as 0 USD
  • If you reconcile after 4:14 PM for the 3:30 PM timestamp, it will show the correct balance
If your reconcile_at timestamp falls after the last balance update but before the next one, the policy will return 0 because the balance at that exact time is unknown.

​
Recommendations

  • Consider using a shorter polling period (e.g., 1 minute instead of 1 hour) for more frequent balance updates
  • Schedule reconciliations to run shortly after known balance update times
  • Ensure your reconcile_at timestamp falls between the last updated balance and the previous one