Create a new payout
Creates a new payout to transfer funds to a payee using their default payment method. Supports payouts from the main account and from subaccounts, in both test and live. subaccount_id is required when the main account has any subaccount, or when the bank config is a Root FBO.
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
Response Body
Note: Use amount_in_minor_units in request bodies. The amount_in_cents field is deprecated and retained in responses for backward compatibility.
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 payout with the same idempotency key already exists and no further work is needed for this request, the existing payout is returned.
- 201 Created: If no payout exists with the provided idempotency key, a new payout is created.
- With
auto_approve=true, an idempotency match that is stillCREATEDcontinues approve→initiate (same as a fresh create+auto_approve). A match inCANCELEDorFAILEDreturns 409 (so after you cancel a payout, reusing its key withauto_approve=truereturns 409; use a new key). Withauto_approve=false, a match always returns the existing payout with 200, whatever its status.
Success Responses
Error Responses
Auto-approve behavior
When auto_approve=true, the API creates the payout (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 payout id is always in the response. If you receive 202, poll
GET /api/payouts/{id}untilstatusreaches a value you treat as final for your integration. - 207: Creation succeeded but approval failed; read
warningandstatus(stillCREATED). See Handling a 207 below. - 503: Transient error while starting async initiation—retry the create; use the response
message(anderror_code) for support and automation.
Handling a 207
A 207 is returned only by create with auto_approve=true. The payout was created (the id is in the body), but the synchronous approval checks did not pass, so the payout stays CREATED. Nothing was sent to the bank, and no funds moved. The warning field says that approval failed. It does not give the reason.
Common causes:
- The payee’s payment method is no longer
verifiedor active (for example, its verification status changed or it was deleted after the payout was created). - The amount is outside the limits for the selected rail.
- The payee’s address is incomplete (required for some rails).
- The card on file has expired, or an
instant_cardpayment method has no card token.
What to do:
- Find the reason: call
POST /api/payouts/{id}/approve. It runs the same checks and returns a 4xx with a specificerror_codeandmessage. - Fix the cause. If the payment method is pending verification, wait for the
payment_method.verifiedwebhook. - Approve the payout: call
POST /api/payouts/{id}/approve, or resend the create request with the sameIdempotency-Keyandauto_approve=true. The resend does not create a second payout; it continues approval of the existing one. - If you no longer want the payout, cancel it with
DELETE /api/payouts/{id}. After a cancel, a create with the same key andauto_approve=truereturns 409.
Do not create a new payout with a new key to work around a 207. The first payout still exists in CREATED until you approve or cancel it.
Authentication
RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.
Headers
Request
Amount in the currency’s minor units (e.g. cents for USD).
Subaccount to debit. Required when the main account has any subaccount, or when the bank config is a Root FBO; otherwise omit to debit the main account. Missing when required returns 422 subaccount_id_required.
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.
Deprecated. Use amount_in_minor_units instead. Still accepted and returned for backward compatibility.
Response
Payout retrieved successfully (idempotency retry)