Production readiness

Prepare your Roots integration for production by validating access controls, lifecycle handling, reconciliation, and the production API contract.

Review API versions and Beta status before enabling any workflow in production.

Before you begin

Generate a dedicated API key for each application and environment.
Store every API-key secret in a secret manager; Roots shows the secret only when the key is created.
Record the Roots IDs and your external references for every person, account, counterparty, payment, and RFI.
Assign owners for credential rotation, reconciliation, operational exceptions, and compliance requests.

1. Confirm production access

Complete these checks before connecting an application to a production environment:

Confirm the production base URL and authentication method with Roots.
Confirm which API-key role each service needs: COMPANY_ADMIN, OPERATOR, or VIEWER.
Verify that the service account or user is active and belongs to the intended company.
Generate a separately labeled API key for each deployed service.
Define a rotation process that creates and deploys a replacement key before revoking the old key.

Do not share a key between unrelated services or environments. Use the key label to identify the owning application and environment, for example production-payments-service.

2. Verify the released API contract

Before enabling an integration workflow, verify the production API reference for every endpoint it uses.

Workflow	Confirm before enabling it
End-customer onboarding	Authentication, required business and associated-person fields, document upload contract, review-submission endpoint, and review-status responses.
Account management	Account-issuance conditions, account statuses, account-instruction availability, and balance semantics.
Counterparties	Required destination data, screening status, update and re-screening behavior, and allowed payment rails.
Payments	Payment request schema, idempotency behavior, status model, settlement events, failure responses, and return handling.
RFIs	Response endpoint, document requirements, deadlines, notification events, and the effects of each request status.
Webhooks	Event catalogue, endpoint registration process, signature verification, retries, and replay behavior.

Do not rely on mock schemas as the final production contract. The production API may add required fields, authentication, authorization rules, lifecycle states, and error responses.

3. Enforce lifecycle gates in your application

Build explicit checks before each dependent action:

Do not create an account for an end customer until the required onboarding and approval flow completes.
Do not treat an issued or pending account as active for funding or outgoing payments.
Do not create a payment to a counterparty until Roots reports that it is active.
Do not treat a payment-create response as confirmation of settlement.
Stop automatic processing when an RFI, hold, restriction, failed review, or non-terminal payment status applies.
Re-fetch the relevant resource after a review or RFI resolves; one cleared condition does not guarantee that every linked control is cleared.

4. Reconcile balances and payments

Maintain an internal ledger or reconciliation record that links each Roots object to your own identifiers.

For each payment, store:

Roots payment ID and your external_id.
Source and destination IDs.
Requested amount and currency.
Payment purpose and description.
Current status and each observed status change.
Creation, submission, settlement, failure, or return timestamps when Roots provides them.

Use available balance—not current balance alone—to decide whether funds can be used. Incoming funds can remain unavailable while compliance checks are in progress, and outgoing payments can lock funds before they settle.

5. Prepare exception handling

Define operational handling before go-live.

Condition	Required behavior
Invalid credentials or inactive user	Stop requests and alert the access-control owner.
API-key secret lost or exposed	Deploy a replacement key, then revoke the affected key.
Counterparty pending or blocked	Do not create a payment to the counterparty.
Payment pending or submitted	Continue monitoring; do not report funds as delivered.
Payment failed or returned	Reconcile the account before issuing a replacement instruction.
RFI open or in review	Keep the affected workflow blocked and collect the requested evidence.
Account on hold or restricted	Do not attempt to bypass the restriction; wait for the Roots outcome.

Optional: Test your webhook handling

When Roots publishes webhook support, test your receiver before enabling production events:

Verify the request signature using the documented scheme.
Persist the event ID before processing the event.
Make processing idempotent so duplicate deliveries do not create duplicate actions.
Return a successful response only after your system has safely recorded the event.
Reconcile webhook events with resource retrieval, especially before changing payment or funds availability in your system.

Go-live checklist

Production endpoints and authentication are confirmed by Roots.
API-key roles, ownership, storage, and rotation procedures are documented.
Required onboarding data and document workflows are implemented against the released API.
Your integration handles review, RFI, account, counterparty, and payment states.
Balance and payment reconciliation uses Roots IDs and your own external references.
Payment retries cannot create duplicate payment instructions.
Your team can respond to RFIs and payment exceptions within the required operational timeframe.
Webhook processing is verified when event delivery becomes available.
Roots has confirmed that the applicable product, rails, jurisdictions, and production capabilities are enabled for your company.