Reconcile balances and payments
Reconcile Roots balances and payment outcomes using available funds and lifecycle status.
Reconcile Roots account balances and payment outcomes so your ledger reflects funds that are recorded, available, pending, settled, failed, or returned.
See API versions and Beta status before using this workflow in production.
Before you begin
- Store Roots account, payment, counterparty, and person IDs with your internal records.
- Store your
external_idfor each payment instruction. - Define an internal process for pending funds, payment failures, returns, RFIs, and holds.
Use current and available balance correctly
A current balance represents funds recorded in the account. An available balance represents the portion of those funds that Roots makes available for new activity after applicable holds, reviews, and pending payment locks.
Do not calculate spendable funds from current balance alone. Use the available balance before creating a payment.
Reconcile payment outcomes
For every payment, retain:
| Record | Why you need it |
|---|---|
Roots payment ID and your external_id | Match Roots activity to your internal instruction. |
| Source and destination IDs | Identify the affected account and counterparty. |
| Amount, currency, purpose, and description | Verify that the settled or returned result matches the intended instruction. |
| Current payment status | Determine whether the payment remains in progress or has a terminal outcome. |
| Relevant timestamps | Reconcile creation, submission, settlement, failure, and return events when Roots provides them. |
A Settled payment represents completion. A Failed or Returned payment requires account reconciliation before you create a replacement.
Handle unavailable funds
Incoming funds can remain unavailable while Roots completes required screening or reviews an exception. Outgoing payments can lock funds while they are pending.
When Roots reports an RFI, hold, restriction, or non-terminal payment state:
- Keep the affected funds or workflow unavailable in your application.
- Route the case to the team responsible for supplying information or resolving the exception.
- Retrieve the latest account and payment state after Roots resolves the linked request.
Retrieve activity
Use the account endpoints to plan reconciliation retrieval:
GET /frontoffice/accounts/{account_id}GET /frontoffice/accounts/{account_id}/transactionsGET /frontoffice/accounts/{account_id}/payments
Next steps
- Track payment status for payment lifecycle handling.
- Respond to RFIs and understand holds for blocked-activity handling.
- Read Core concepts for current and available balance definitions.
Updated about 1 hour ago