Approve single payout

{
  "data": {
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:35:00Z",
    "id": "a3f1c9e2-4b7d-4f2a-9c3e-8d2b7f6a1e4c",
    "payee_id": "d9f8a7b6-1234-4cde-9f8a-56789abcdef0",
    "amount_in_cents": 15000,
    "amount_in_minor_units": 15000,
    "currency_code": "USD",
    "country_code": "US",
    "rail": "instant_card",
    "payout_metadata": {
      "invoice_id": "INV-20240115-001",
      "notes": "Monthly contractor payout"
    },
    "status": "approved",
    "status_recorded_at": "2024-01-15T09:35:00Z",
    "client_metadata": {
      "request_id": "req_20240115_001",
      "source": "web_portal"
    }
  },
  "warning": null
}

Approves a single payout in CREATED status and starts bank processing. The payout must belong to your entity.

Response body

Field	Type	Description
`data`	Object	The payout object (`status` reflects the state at response time)
`warning`	String	Present on 207 when initiation had a recoverable issue

Success responses

Status Code	Description
201	The payout was approved and processing continued; `data.status` reflects the outcome of this request.
202	The request was accepted and `data` includes the payout, but `data.status` may still change. Poll `GET /api/payouts/{id}` (or your usual list/events flow) until the payout reaches a terminal status.
207	The payout was approved but initiation did not complete successfully; see `warning` and `data.status`.

Error and retry responses

Status Code	Error code	Description
400	(see response)	The payout cannot be approved in its current state.
404	(see response)	Payout not found for this entity.
503	(see response body)	Transient error—bank initiation did not complete for this request. Retry the same approve call after a short wait. The JSON body includes `error_code` and `message` for logging and automation.

Notes

Treat 202 like any accepted operation: use the returned id and poll until status stabilizes.
503 is for retries, not a final business outcome for the transfer.

Approves a single payout in **CREATED** status and starts bank processing. The payout must belong to your entity. **Response body** | Field | Type | Description | |-------|------|-------------| | `data` | Object | The payout object (`status` reflects the state at response time) | | `warning` | String | Present on **207** when initiation had a recoverable issue | **Success responses** | Status Code | Description | |-------------|-------------| | **201** | The payout was approved and processing continued; **`data.status`** reflects the outcome of this request. | | **202** | The request was accepted and **`data`** includes the payout, but **`data.status`** may still change. Poll **`GET /api/payouts/{id}`** (or your usual list/events flow) until the payout reaches a terminal status. | | **207** | The payout was approved but initiation did not complete successfully; see **`warning`** and **`data.status`**. | **Error and retry responses** | Status Code | Error code | Description | |-------------|------------|-------------| | **400** | (see response) | The payout cannot be approved in its current state. | | **404** | (see response) | Payout not found for this entity. | | **503** | (see response body) | **Transient error**—bank initiation did not complete for this request. **Retry** the same approve call after a short wait. The JSON body includes `error_code` and `message` for logging and automation. | **Notes** - Treat **202** like any accepted operation: use the returned id and **poll** until status stabilizes. - **503** is for **retries**, not a final business outcome for the transfer.

Authentication

x-api-keystring

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

Path parameters

payout_idstringRequiredformat: "uuid"

Response

Payout approved and initiated successfully

dataobject or null

warningstring or null

Errors

404

Not Found Error

503

Service Unavailable Error

Approves a single payout in CREATED status and starts bank processing. The payout must belong to your entity.

Response body

Field	Type	Description
`data`	Object	The payout object (`status` reflects the state at response time)
`warning`	String	Present on 207 when initiation had a recoverable issue

Success responses

Status Code	Description
201	The payout was approved and processing continued; `data.status` reflects the outcome of this request.
202	The request was accepted and `data` includes the payout, but `data.status` may still change. Poll `GET /api/payouts/{id}` (or your usual list/events flow) until the payout reaches a terminal status.
207	The payout was approved but initiation did not complete successfully; see `warning` and `data.status`.

Error and retry responses

Status Code	Error code	Description
400	(see response)	The payout cannot be approved in its current state.
404	(see response)	Payout not found for this entity.
503	(see response body)	Transient error—bank initiation did not complete for this request. Retry the same approve call after a short wait. The JSON body includes `error_code` and `message` for logging and automation.

Notes

Treat 202 like any accepted operation: use the returned id and poll until status stabilizes.
503 is for retries, not a final business outcome for the transfer.

$	curl -X POST https://api.useroot.com/api/payouts/payout_id/approve \
>	-H "x-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{}'