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.

Payout Status Lifecycle

Payouts transition through the following statuses:

Status Transition Flow

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.

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):

1
{
2
  "data": [
3
    {
4
      "id": "po_123456789",
5
      "status": "initiated",
6
      "amount_in_cents": 5000,
7
      "amount_in_minor_units": 5000,
8
      "currency_code": "USD",
9
      "country_code": "US",
10
      "created_at": "2023-10-15T14:30:00Z",
11
      ...
12
    }
13
  ],
14
  "pagination": {
15
    "next_cursor": "cursor_value",
16
    "has_more": true
17
  }
18
}

Supported Rails and SLAs

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

Bank Account Rails

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

Card Rails

Cards only support the “instant_card” rail option.