Track payment status

Track each Roots payment until it reaches a terminal outcome and reconcile its effect on your account records.

See API versions and Beta status before using this workflow in production.

Before you begin

Store the Roots payment ID and your external_id when you create a payment.
Store the source and destination IDs, requested amount, currency, and payment purpose.
Design your application so a payment is not reported as delivered until Roots reports a settled outcome.

Payment statuses

The current payment schema exposes these statuses:

Status	Meaning	Integration behavior
`Pending`	The payment has been created but is not settled.	Keep the payment in progress. Do not report delivery.
`Submitted`	The payment has been submitted for processing.	Continue monitoring for a terminal status.
`Settled`	The payment has completed.	Reconcile the completed payment with your internal ledger.
`Failed`	The payment did not complete.	Investigate the failure before creating a replacement instruction.
`Returned`	The payment was returned after processing began.	Reconcile the returned funds before creating a replacement instruction.

Retrieve the latest state

Use the payment and account-payment retrieval endpoints to plan status retrieval:

GET /frontoffice/payments
GET /frontoffice/accounts/{account_id}/payments

Always retrieve the latest payment state rather than relying on the initial create response. A payment can remain unavailable while Roots completes required checks or reviews an exception.

Handle terminal outcomes

When a payment reaches Settled, store the final status and any returned settlement details. When it reaches Failed or Returned, reconcile the account first and determine whether a new instruction is appropriate.

Do not retry automatically without a confirmed production idempotency and error contract. See API versions and Beta status for the information to confirm before enabling production retries.

Next steps

Reconcile balances and payments to reconcile account balances and payment outcomes.
Respond to RFIs and understand holds when a payment requires additional information or remains blocked.