Skip to navigation

Create a new subaccount

View as Markdown

Creates a new subaccount for fund segregation within your root entity’s main account.

Request Body

FieldTypeRequiredDescriptionValidation Rules
nameStringYesName of the subaccountMust be between 1 and 100 characters

Response Body

FieldTypeDescription
idUUIDUnique identifier of the subaccount
nameStringName of the subaccount
account_numberStringAccount number for deposits
routing_numberStringDeprecated: use routing_numbers.ach. Kept for backward compatibility
routing_numbersObjectRouting numbers per rail (see below)
routing_numbers.achStringACH routing number for ACH transfers
routing_numbers.wireStringWire routing number for wire transfers. For JPM VRNs with separate wire config, differs from ach. For other banks, same as ach.
total_incoming_in_minor_unitsIntegerTotal incoming funds in the smallest unit of the account’s currency (settled payins + incoming moves) - initially 0
total_outgoing_in_minor_unitsIntegerTotal outgoing funds in the smallest unit of the account’s currency (settled/debited payouts + outgoing moves) - initially 0
created_atDateTimeISO 8601 timestamp when the subaccount was created
updated_atDateTimeISO 8601 timestamp when the subaccount was last updated

Virtual Banking Details

Upon creation, each subaccount is assigned virtual banking details that can be shared with payers for direct deposits:

  • Account Number: Unique account number for receiving deposits
  • Routing Numbers: Use routing_numbers.ach for ACH transfers. For JPM VRNs, use routing_numbers.wire for wire transfers (same account number, different routing number per rail).

Use these details to configure payment processors to route funds to specific subaccounts.

Error Responses

Statuserror_codeWhen
400VALIDATION_ERRORRequest body failed validation (e.g. invalid or missing name)
400VALIDATION_ERRORSubaccounts are not supported for your operating account currency (e.g. non-USD main account while that capability is unavailable)

Authentication

x-api-keystring

RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.

Request

This endpoint expects an object.
namestringRequired1-100 characters
Name of the subaccount

Response

Subaccount created successfully