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

# Payins API

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

## Payins

A **Payin** represents a money transfer from a payer using their default payment method. Payins go through various status transitions and are processed according to the specified rail.

### Payin Status Lifecycle

Payins transition through the following statuses:

| Status | Description |
|--------|-------------|
| `initiated` | The payin has been created and sent to the banking partner, funds are in transit. |
| `settled` | The payin has been successfully completed and funds have been received. |
| `failed` | The payin has encountered an error and could not be completed despite retry attempts. |


### Status Transition Details

1. **Created → Initiated**
   - Occurs automatically when the payin is created
   - The payin is immediately sent to the banking system
   - Funds are now in transit from the payer

2. **Initiated → Settled**
   - Occurs when confirmation is received that funds have been received
   - Processing time varies by payment rail (ACH, RTP, etc.)

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

### Approval Process

Payins support an optional approval workflow controlled by the `auto_approve` parameter:

- **Manual Approval (Recommended)**: By default, `auto_approve` is set to `false`. This creates the payin in `created` status, requiring explicit approval before funds are collected. This gives you greater control through your UI approval flow.
- **Automatic Approval**: Setting `auto_approve` to `true` immediately transitions the payin to `approved` and `initiated` status upon creation, sending it directly to the banking system.

**Best Practice**: It's recommended to keep `auto_approve` as `false` for payins to maintain better control over fund collection through an approval workflow in your application UI.

## Supported Rails and SLAs

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

### ACH Rails

| Rail | Name | Description | SLA |
|------|------|-------------|-----|
| `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 |

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

**Note**: Payins only support Same-Day ACH and Standard ACH rails. Instant bank transfers (RTP/FedNow), wire transfers, and card payments are not supported for payins.