Introduction

Root is an instant money movement platform that connects directly to your bank and enables you to configure and initiate money movement workflows intelligently. Its simple to implement and free to get started.

If you’re a marketplace with high money movement volume, you’re likely using platforms like Stripe, Hyperwallet, Payoneer, or Bill.com, for various workflows like account receivables, account payables, mass payouts & disbursements. Each of these platforms are practically closed loop systems (you have to pre-fund and hold money in those accounts) charging high fees, slow processing times, and complex reconciliation processes. Building this functionality directly on your existing bank infrastructure might seem like an option, but it’s costly, time-consuming, and riddled with technical challenges. Root seamlessly connects to your existing bank accounts, simplifying workflows with just a few API calls. It eliminates inefficiencies, delivers faster transactions (in many cases near instant settlements), ensures reliable reconciliation, and saves you money.

This guide will walk you through implementing Root in your system.

API Reference

The Root API follows REST principles with JSON-encoded requests and responses. You’ll find familiar HTTP methods, standardized response codes, and predictable URL patterns.

Key Features

• Seamless Integration: Use test mode to simulate payout operations without touching live data or financial networks. Your API key determines whether you’re working in test mode or live mode.

• Single & Bulk Operations: Perform single-object actions or handle bulk updates with ease, giving you full control over how you manage payouts.

• Evolving with You: The API adapts through versioning and customizations specific to your account, so it grows alongside your needs.

Getting Started

This guide takes you through each step of managing payouts—from setting up your environment to running tests, and finally deploying to production. Here’s the roadmap:

• Configure Your Environment: Get your API keys and configure your environment

• Test Your Integration: Use test mode to verify your implementation works correctly

• Go Live: Switch to live mode when you’re ready to process real transactions

Test Mode vs. Live Mode

Your API key determines which mode you’re in:

• Test Mode: Safely simulate API calls in a sandbox environment. Test mode keys are only valid in this environment and do not affect live data or external systems. Test mode credentials are prefixed with test_.

• Live Mode: Once your integration is tested and ready, switch to live mode to interact with real data and systems. Live mode credentials are prefixed with live_.

Each mode uses separate API keys. Be cautious when switching between modes to avoid unintended interactions. You can find more about the test environemt in the Test Environment section.

API Authentication

All API requests require an API key for authentication. This key uniquely identifies your account and ensures only authorized users can access your data.

Using API Key Authentication

• To authenticate your requests, include your API key in the X-API-KEY HTTP header:

X-API-KEY: [YOUR_API_KEY]

Ensure your API key is kept secure:

• Do not expose your API key in publicly accessible locations, such as GitHub repositories or client-side code.

• Rotate your API key periodically to minimize security risks.

Pagination

You can paginate through lists of objects using cursor-based pagination. Each list endpoint supports this feature. This is a forward-only pagination system that returns objects in chronological order. You can control pagination using these parameters:

• limit: Set the number of objects per page (default varies by endpoint, max: 100)

• cursor: Get objects created after a specific object ID (forward pagination only)

• order: Sort order by created_at - “desc” for newest first (default), “asc” for oldest first

Note: This implementation supports forward-only pagination. You can move forward through pages by using the next_cursor from the previous response.

Example

// Get the first page (newest first by default)
GET /api/payouts?limit=25
// Get oldest first instead
GET /api/payouts?limit=25&order=asc
// Get the next page using the next_cursor from previous response
GET /api/payouts?limit=25&cursor=payout_cursor_123&order=desc

Response Format

The API response includes pagination metadata to help you navigate through pages:

{
  "data": [...],
  "has_more": true,           // More pages exist
  "total_count": 150,         // Total number of records
  "next_cursor": "payout_cursor_148", // Use this cursor to get the next page
  "previous_cursor": "payout_cursor_123" // The cursor used to get current page (for reference)
}

Pagination Flow:

• First page: Make a request without a cursor parameter
• Subsequent pages: Use the next_cursor value from the previous response as the cursor parameter
• End of results: When has_more is false, you’ve reached the end

Idempotency

All transfer creation requests support idempotency to help you safely retry operations without creating duplicate transactions. This is particularly useful when your API call fails and you aren’t sure if your request was received.

To make an idempotent request, add an Idempotency-Key header with a unique value:

Idempotency-Key: <your-unique-key>

When you include this header, we’ll ensure that multiple requests with the same key return the same result, preventing duplicate operations. The first request creates the transfer, while subsequent requests with the same key return the original result.

Example: Request Without Idempotency

Here’s a transfer request without an Idempotency-Key header:

$
curl --location https://api.useroot.com/api/payouts --header 'Content-Type: application/json' --header 'X-API-KEY: [YOUR_API_KEY]' --data '{
>
    "payee_id": "0862d70b-e74d-428e-99f5-11e942e23d90",
>
    "amount_in_minor_units": 100,
>
    "currency_code": "USD"
>
}'

If this API call is repeated (for example, if a user double-clicks a submit button in your web interface), it could create duplicate transfers and cause double spending.

Example: Using Idempotency

Here’s how to prevent duplicate transfers using an Idempotency-Key:

$
# First request
$
curl --location https://api.useroot.com/api/payouts -H "Idempotency-Key: 1zByArFNupaumBTijz3XXTlj9ZL"
$
--header 'Content-Type: application/json' --header 'X-API-KEY: [YOUR_API_KEY]' --data '{
>
    "payee_id": "0862d70b-e74d-428e-99f5-11e942e23d90",
>
    "amount_in_minor_units": 100,
>
    "currency_code": "USD"
>
}'
$
# Second request with same Idempotency-Key
$
curl --location https://api.useroot.com/api/payouts -H "Idempotency-Key: 1zByArFNupaumBTijz3XXTlj9ZL"
$
--header 'Content-Type: application/json' --header 'X-API-KEY: [YOUR_API_KEY]' --data '{
>
    "payee_id": "0862d70b-e74d-428e-99f5-11e942e23d90",
>
    "amount_in_minor_units": 100,
>
    "currency_code": "USD"
>
}'

In this example, both requests include the same Idempotency-Key. Only the first request creates a transfer - the second request returns the result of the first operation, preventing any duplicate transfers.

Safe Retry Guide

Idempotency keys are looked up by key only (not by request body comparison). This means you can safely retry requests with the same idempotency key after any error.

When to retry with the same key:

• After network errors or timeouts
• After 500 Internal Server Error or 503 Service Unavailable
• After any unexpected error where you’re unsure if the request was processed

Response codes:

• 200 OK: Resource already exists - safe to use the returned resource
• 201 Created: New resource was created
• 400 Bad Request: Validation error - fix your request before retrying

Example: Retry after error

$
# First request fails with 500 error
$
curl --location https://api.useroot.com/api/payouts -H "Idempotency-Key: retry-key-123" --header 'Content-Type: application/json' --header 'X-API-KEY: [YOUR_API_KEY]' --data '{
>
    "payee_id": "0862d70b-e74d-428e-99f5-11e942e23d90",
>
    "amount_in_minor_units": 100,
>
    "currency_code": "USD"
>
}'
$
# Returns: 500 Internal Server Error
$
$
# Retry with same idempotency key - safe!
$
curl --location https://api.useroot.com/api/payouts -H "Idempotency-Key: retry-key-123" --header 'Content-Type: application/json' --header 'X-API-KEY: [YOUR_API_KEY]' --data '{
>
    "payee_id": "0862d70b-e74d-428e-99f5-11e942e23d90",
>
    "amount_in_minor_units": 100,
>
    "currency_code": "USD"
>
}'
$
# Returns: 200 OK with existing payout (if created) or 201 Created (if not)

Error Handling

We provide detailed error responses to help you quickly identify and resolve issues.

HTTP Status Codes

The HTTP status code indicates the general category of the response:

Error Response Format

Every error response includes these fields:

1
{
2
  "type": "",
3
  "code": "",
4
  "message": "",
5
  "documentation_url": "https://docs.root.credit",
6
  "details": null
7
}

Understanding Error Fields

• type: The broad category of the error

• code: A specific error identifier you can handle programmatically

• message: A developer-friendly explanation of what went wrong

• documentation_url: A link to relevant documentation

• details: Additional information about the error (when available)

Note: The message field may change over time. For stable error handling, use the code field in your logic.

Error Categories

You may encounter these error types:

• authentication_error: API key and permission issues

• bank_account_error: Problems with bank account operations

• dashboard_error: Dashboard-related issues

• server_error: System-level problems we’re actively monitoring

• transfer_error: Transfer operation issues

• validation_error: Request formatting and parameter problems