Create transfers

Create an internal transfer or an ACH or Fedwire withdrawal from an eligible Roots account.

See API availability before you process production transfers.

Before you begin

• Obtain a bearer access token.
• Retrieve the source account and confirm that balance.available covers the transfer amount.
• Retrieve the counterparty and confirm it is eligible before a withdrawal.
• Generate a unique Idempotency-Key for the transfer request.

Use minor units

Send amount as an integer in minor units of the account currency. For USD, send cents.

Never send a decimal or major-unit value such as 1250.5.

Create an internal transfer

Create an internal transfer with POST /api/v1/client/transfers.

{
  "direction": "internal",
  "account_id": "acct_source_123",
  "destination_account_id": "acct_destination_456",
  "amount": 5000
}

Create a withdrawal

Create a withdrawal to an eligible counterparty with POST /api/v1/client/transfers.

{
  "direction": "withdrawal",
  "account_id": "acct_123",
  "counterparty_id": "cpty_123",
  "amount": 125050,
  "rail": "FEDWIRE"
}

Send these headers with every transfer creation request:

Authorization: Bearer <access-token>
Idempotency-Key: <unique-key>
Content-Type: application/json

The response returns a TransferDetail, including id, status, amount, currency, rail, failure_reason, and lifecycle metadata.

Approve, reject, or rescind a transfer

Use the current transfer status and your authorized workflow to determine whether an action is available:

• POST /api/v1/client/transfers/{transfer_id}/approve
• POST /api/v1/client/transfers/{transfer_id}/reject
• POST /api/v1/client/transfers/{transfer_id}/rescind

Each action requires bearer authentication and an Idempotency-Key. Retrieve the transfer after every action and record the returned state.

Next steps

• Read Track transfer status to retrieve and reconcile the latest transfer record.
• Read Reconcile balances and transfers for balance-bucket handling.
• Read Idempotency before you implement retries.