Reconcile balances and transfers

Reconcile Roots account balance buckets and transfer records using minor-unit amounts and current resource state.

See API availability before you use reconciliation behavior in production.

Before you begin

Store Roots person, account, counterparty, and transfer IDs with your internal records.
Store amounts as integer minor units or decimal strings, not binary floating-point values.
Retrieve the current account and transfer record before you post a final ledger outcome.

Reconcile account balances

GET /api/v1/client/accounts/{account_id} returns balance buckets as decimal strings in minor units.

Field	Use in reconciliation
`balance.available`	Funds eligible for new activity.
`balance.payin_pending_total`	Inbound funds that are not yet available.
`balance.payout_pending_total`	Funds committed to pending outgoing transfers.
`balance.restricted_compliance_total`	Funds unavailable because of compliance controls.
`balance.restricted_legal_total`	Funds unavailable because of legal controls.

For USD, treat "125050" as USD 1,250.50. Convert only for display; preserve the minor-unit value for reconciliation and transfer creation.

Reconcile transfers

GET /api/v1/client/transfers/{transfer_id} returns a transfer amount as a decimal string in minor units.

For every transfer, retain:

Record	Why you need it
Roots transfer ID	Links your instruction to the Roots record.
Account, destination account, and counterparty IDs	Identifies the affected parties and accounts.
`direction`, `rail`, `amount`, and `currency`	Verifies the requested money movement.
`status` and `failure_reason`	Determines the current operational outcome.
`rail_refs` and `business_date`	Supports rail-level and accounting reconciliation.
`created_at`, creating identity, and approving identity	Supports operational audit trails.

Handle pending and restricted funds

Do not create a new transfer from funds that are included in pending or restricted buckets. Use only balance.available for a new transfer amount.

When compliance or legal restrictions apply, keep the affected activity unavailable in your application. Resolve associated cases through the approved operational workflow, then retrieve the latest account and transfer records before releasing downstream activity.

Next steps

Read Manage accounts for account balance definitions.
Read Track transfer status for transfer retrieval.
Read Idempotency before you retry an uncertain write.