> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.useroot.com/api-reference/payouts-api/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.useroot.com/_mcp/server.

# Payouts API

The **Payouts API** enables you to initiate payouts and list all created payouts. Each payout is processed according to the specified rail and goes through various status transitions.

## Payouts

A **Payout** represents a money transfer to a payee using their default payment method. Payouts go through various status transitions and are processed according to the specified rail.

<img src="https://content.pstmn.io/5fb72cb6-0371-499d-9610-eaff3bff3c23/Q3JlYXRlUGF5b3V0cy5naWY=" alt="Create%20Payouts" />

### Payout Status Lifecycle

Payouts transition through the following statuses:

| Status | Description |
|--------|-------------|
| `created` | Initial status when a payout is successfully created. Payouts cannot be modified after creation, but can be canceled. |
| `canceled` | The payout has been canceled and will not be processed further. |
| `approved` | The payout has been approved and queued for processing. This status initiates the payment process. |
| `initiated` | The payout has been sent to the banking partner and funds are in transit. |
| `debited` | For ACH payments only - indicates that funds have been successfully debited from the sender's account. |
| `settled` | The payout has been successfully completed and funds have reached the recipient. |
| `failed` | The payout has encountered an error and could not be completed despite retry attempts. |

### Status Transition Flow

<img src="https://content.pstmn.io/a8887413-b973-49e3-b9dc-c9434224f947/TWVybWFpZCBDaGFydC5wbmc=" />

### Status Transition Details

1. **Created → Approved**
   - Occurs when the payout is approved via the dashboard or with the `auto_approve` option
   - Payouts in the created state can only be canceled, not modified

2. **Created → Canceled**
   - Occurs when you explicitly cancel a payout before it's approved
   - Available through the dashboard interface

3. **Approved → Initiated**
   - Occurs when the payout is accepted by the banking system
   - Typically happens within minutes of approval
   - Funds are now in transit to the recipient

4. **Initiated → Debited** (ACH only)
   - Occurs when funds have been successfully debited from the sender's account
   - Only applies to ACH payment rails (standard and same-day)

5. **Initiated → Settled** (non-ACH rails)
   - Occurs when confirmation is received that funds have reached the recipient
   - Processing time varies by payment rail (ACH, wire transfer, etc.)

6. **Approved/Initiated → Failed**
   - Occurs when a payout cannot be completed due to an error
   - Common causes: insufficient funds, invalid banking details, or compliance issues
   - Failed payouts cannot be reprocessed and require creating a new payout

### Auto-Approve Feature

You can set `auto_approve: true` when creating a payout to automatically transition it from `created` to `approved` state without requiring manual approval through the dashboard.

<img src="https://content.pstmn.io/0c5627df-8732-4f87-aeea-7c7646418de1/QXBwcm92ZVBheW91dC5naWY=" alt="Approve%20Payouts" />

### Querying Payouts by Status

```
GET https://api.useroot.com/api/payouts?status=initiated
```

Example response (amount fields are dual-emitted for compatibility; `amount_in_cents` is the legacy name and matches `amount_in_minor_units` for USD minor units):
```json
{
  "data": [
    {
      "id": "po_123456789",
      "status": "initiated",
      "amount_in_cents": 5000,
      "amount_in_minor_units": 5000,
      "currency_code": "USD",
      "country_code": "US",
      "created_at": "2023-10-15T14:30:00Z",
      ...
    }
  ],
  "pagination": {
    "next_cursor": "cursor_value",
    "has_more": true
  }
}
```

## Supported Rails and SLAs

The Payouts API supports different payment rails with varying processing times and service level agreements (SLAs):

### Bank Account Rails

| Rail | Name | Description | SLA |
|------|------|-------------|-----|
| `instant_bank` | Instant Bank Transfer | Immediate bank transfer | Funds typically available within minutes, 24/7 |
| `same_day_ach` | Same-Day ACH | Expedited ACH transfer | Funds typically available same business day if initiated before 1 PM ET |
| `standard_ach` | Standard ACH | Standard ACH transfer | Funds typically available in 1-3 business days |
| `wire` | Wire Transfer | Bank wire transfer | Funds typically available within hours during business days |

The available rails for bank accounts are determined by the payee's bank routing number. Not all routing numbers support all rails.

### Card Rails

| Rail | Name | Description | SLA |
|------|------|-------------|-----|
| `instant_card` | Instant Card Transfer | Immediate card transfer | Funds typically available within minutes, 24/7 |

Cards only support the "instant_card" rail option.


## API Docs

- Payouts API [List payouts](https://docs.useroot.com/api-reference/payouts-api/list-all-payouts.md)
- Payouts API [Create a new payout](https://docs.useroot.com/api-reference/payouts-api/create-payout.md)
- Payouts API [Approve single payout](https://docs.useroot.com/api-reference/payouts-api/approve-payout.md)
- Payouts API [Get payout by ID](https://docs.useroot.com/api-reference/payouts-api/get-payout-by-id.md)
- Payouts API [Cancel payout](https://docs.useroot.com/api-reference/payouts-api/cancel-payout.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.useroot.com/openapi.json)
- [OpenAPI YAML](https://docs.useroot.com/openapi.yaml)