Move funds between subaccounts
Creates a move to transfer funds between two subaccounts within the same root entity.
Request Headers
Request Body
Examples:
- For USD,
amount_in_minor_units: 1000is 1000 cents = $10.00 - For USD,
amount_in_minor_units: 1250is 1250 cents = $12.50
Approval flow
When auto_approve is true (default), the move is created, approved, and settled in one request — the response has status: "settled".
When auto_approve is false, the move is created in created status. Use POST /api/subaccounts/move/{move_id}/approve to approve and settle it, or DELETE /api/subaccounts/move/{move_id} to cancel it.
Moves do not enforce a minimum source balance — a subaccount may show a negative available balance after settlement.
Response Body
Idempotency Key
You can include an Idempotency-Key header to ensure that duplicate requests are handled safely. When you retry a request with the same idempotency key:
- 200 OK: If a move with the same idempotency key already exists and no further work is needed for this request, the existing move is returned.
- 201 Created: If no move exists with the provided idempotency key, a new move is created.
- With
auto_approve=true(the default), an idempotency match that is stillCREATEDcontinues approve→settle. A match inCANCELEDorFAILEDreturns 409.
Success Responses
Error Responses
Authentication
RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.
Headers
Request
Amount to move in the account currency’s minor units (e.g. cents for USD).
Optional client key-value metadata stored as client_metadata.
Deprecated. Use amount_in_minor_units instead. Still accepted and returned for backward compatibility.
Response
Move retrieved successfully (idempotency retry)