Create account transfer
Creates an account transfer to move funds between two treasury main accounts.
Request Headers
Request Body
Response Body
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 stillCREATEDcontinues approve→initiate. A match inCANCELEDorFAILEDreturns 409.
Success Responses
Error Responses
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
statusreaches a value you treat as final for your integration. - 207: The transfer was created but approval failed; review the
warningand currentstatus(stillCREATED). - 503: Transient error while starting async initiation—retry the create; use the response
message(anderror_code) for support and automation.
Authentication
RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.
Headers
Request
Main operating account ID (Account.id) to send funds from.
Main operating account ID (Account.id) to send funds to.
Payment rail (must be in supported_rails)
Currency code; must match the source account.
Optional client key-value metadata stored as client_metadata.
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.