> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.useroot.com/api-reference/payins-api/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. ## API Docs - [List payins](https://docs.useroot.com/api-reference/payins-api/list-payins.md): Payins API - [Create a new payin](https://docs.useroot.com/api-reference/payins-api/create-payin.md): Payins API - [Get payin by ID](https://docs.useroot.com/api-reference/payins-api/get-payin-by-id.md): Payins API - [Cancel payin](https://docs.useroot.com/api-reference/payins-api/cancel-payin.md): Payins API - [Approve single payin](https://docs.useroot.com/api-reference/payins-api/approve-payin.md): Payins API ## OpenAPI Specification - [OpenAPI JSON](https://docs.useroot.com/openapi.json): raw OpenAPI 3.1 specification for this API, JSON format - [OpenAPI YAML](https://docs.useroot.com/openapi.yaml): raw OpenAPI 3.1 specification for this API, YAML format