Skip to navigation

Create account transfer

View as Markdown

Creates an account transfer to move funds between two treasury main accounts.

Request Headers

HeaderTypeRequiredDescription
Idempotency-KeyStringNoUnique key to prevent duplicate requests. If provided, the same key cannot be used for another account transfer.

Request Body

FieldTypeRequiredDescriptionValidation Rules
from_account_idUUIDYesTreasury account to send funds from.Must be an onboarded main account belonging to your organization
to_account_idUUIDYesTreasury account to receive funds.Must differ from from_account_id
amount_in_minor_unitsIntegerYesAmount in the smallest unit of the currency. For USD, cents (100 = $1.00).Must be a positive whole number
railStringYesPayment rail for the transfer.Must be supported for the source account (see rail-options)
currency_codeStringYesISO 4217 currency code.Must match the source account currency
auto_approveBooleanYesWhen true, automatically approve and initiate the transfer after create.Must be explicitly set; there is no default
metadataObjectNoOptional client key-value metadata.String values only

Response Body

FieldTypeDescription
idUUIDUnique identifier for the account transfer.
from_account_idUUIDSource treasury account ID.
to_account_idUUIDDestination treasury account ID.
amount_in_minor_unitsIntegerTransfer amount in minor units.
currency_codeStringISO 4217 currency code.
railStringPayment rail used.
statusStringCurrent status (created, approved, initiated, settled, failed).
client_metadataObjectClient-supplied metadata.
created_atDateTimeTimestamp when the transfer was created.
updated_atDateTimeTimestamp when the transfer was last updated.

Idempotency Key

When you include an Idempotency-Key header:

  • 200 OK — An account transfer with the same idempotency key already exists and no further work is needed for this request; the existing transfer is returned.
  • 201 Created — A new account transfer was created.
  • With auto_approve=true, an idempotency match that is still CREATED continues approve→initiate. A match in CANCELED or FAILED returns 409.

Success Responses

Status CodeDescription
200OK — existing account transfer returned for the provided idempotency key
201Created — account transfer created; with auto_approve, processing finished within this response for your request (status reflects the result)
202Accepted — account transfer created (and approved when auto_approve is true). status in the body may still change; poll list endpoints until the transfer reaches a terminal status
207Multi-Status — account transfer was created (or already existed as CREATED) but approval failed; transfer remains CREATED with a warning

Error Responses

Status CodeError CodeDescription
400VALIDATION_ERRORInvalid request body, incompatible currency, or incompatible account combination
401AUTHENTICATION_ERRORAuthentication credentials are invalid or missing
403AUTHORIZATION_ERRORYou do not have permission to perform this action
404NOT_FOUNDOne or both treasury accounts were not found
409IDEMPOTENCY_KEY_CONFLICTIdempotency key matches an existing account transfer in a terminal failed or canceled state; use a new key
422Unprocessable EntityRequest body failed schema validation (e.g. missing required fields such as auto_approve or currency_code)
503ASYNC_INITIATION_UNAVAILABLEWith auto_approve, the transfer was created (and approved) but initiation hit a transient error. Retry after a short wait

auto_approve behavior

When auto_approve=true, the API creates the account transfer (or continues from an idempotent CREATED match) and continues approval and async initiation as far as this request allows. You may receive 201, 202, 207, or 503 depending on outcome:

  • 201 / 202: The account transfer id is always in the response. If you receive 202, poll until status reaches a value you treat as final for your integration.
  • 207: The transfer was created but approval failed; review the warning and current status (still CREATED).
  • 503: Transient error while starting async initiation—retry the create; use the response message (and error_code) for support and automation.

Authentication

x-api-keystring

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

Headers

Idempotency-Keystring or nullOptional
Unique key to prevent duplicate requests

Request

This endpoint expects an object.
from_account_idstringRequiredformat: "uuid"

Main operating account ID (Account.id) to send funds from.

to_account_idstringRequiredformat: "uuid"

Main operating account ID (Account.id) to send funds to.

amount_in_minor_unitsintegerRequired
Transfer amount in the source account currency minor units.
railenumRequired

Payment rail (must be in supported_rails)

currency_codeenumRequired

Currency code; must match the source account.

Allowed values:
auto_approvebooleanRequired
When true, approve and initiate immediately after create.
metadatamap from strings to strings or nullOptional

Optional client key-value metadata stored as client_metadata.

scheduled_datedate or nullOptional

Calendar day to release the transfer in its schedule timezone (currently America/New_York). Omitted for immediate. Not the beneficiary credit date. Resolved to 09:00 in that timezone.

Response

Existing account transfer returned for idempotency key

Errors

409
Conflict Error
503
Service Unavailable Error