Create a new payin

Creates a new payin to collect funds from a payer using their payment method. A payin represents an ACH debit transaction that pulls money from the payer’s bank account. Supports both regular payins and subaccount payins (test entities only).

Request Body

Field	Type	Required	Description	Validation Rules
`payer_id`	UUID	Yes	ID of the payer from whom to collect funds.	Must be a valid UUID for an existing payer
`amount_in_minor_units`	Integer	Yes	Amount in the smallest unit of the currency. For USD, this is cents (100 = $1.00).	Must be a positive whole number.
`currency_code`	String	No	ISO 4217 currency code. Defaults to the source account’s currency.	If supplied, must match a supported country and currency combination for debit.
`rail`	String	No	Payment rail to use. Options: `standard_ach`, `same_day_ach`. Uses default if not provided.	Must be one of the supported ACH rails
`payment_method_id`	UUID	No	ID of a specific payment method to use instead of the payer’s default payment method.	Must be a valid UUID for an existing payment method belonging to the payer
`subaccount_id`	UUID	No	ID of the subaccount to credit to (test entities only). When provided, the payin will be credited to the specified subaccount instead of the main account.	Must be a valid UUID for an existing subaccount belonging to the entity. Only available for sandbox/test entities.
`auto_approve`	Boolean	No	If set to true, payin will automatically transition to approved and initiated state.	default: `false`
`metadata`	Object	No	Arbitrary metadata as key-value pairs to store with the payin for your own reference.	Must be an object with string keys and string values. Maximum 50 keys, each key max 40 characters, each value max 500 characters, total size max 16KB.

Examples:

For USD, amount_in_minor_units: 2500 is 2500 cents = $25.00
For USD, amount_in_minor_units: 10075 is 10075 cents = $100.75

Response Body

Field	Type	Description
`id`	UUID	Unique identifier for the payin.
`payer_id`	UUID	ID of the payer from whom funds are being collected.
`subaccount_id`	UUID	ID of the subaccount this payin is attributed to. Null if attributed to main account.
`status`	String	Current status of the payin (`created`, `canceled`, `approved`, `initiated`, `debited`, `settled`, `failed`)
`amount_in_minor_units`	Integer	The payin amount in the smallest unit of the currency. For USD, cents (100 = $1.00).
`amount_in_cents`	Integer	Deprecated alias for `amount_in_minor_units`.
`currency_code`	String	ISO 4217 currency code of the destination account.
`country_code`	String	ISO 3166-1 alpha-2 country code of the destination account.
`rail`	String	Payment rail used (standard_ach, same_day_ach)
`payin_metadata`	Object	Contains payment method details and payer information (sensitive data is masked)
`client_metadata`	Object	Arbitrary metadata as key-value pairs that were provided when creating the payin
`status_recorded_at`	DateTime	Timestamp when the current status was recorded
`created_at`	DateTime	Timestamp when the payin was created
`updated_at`	DateTime	Timestamp when the payin was last updated

Note: Use amount_in_minor_units in request bodies. The amount_in_cents field is deprecated and retained in responses for backward compatibility.

Idempotency Key

You can include an Idempotency-Key header to ensure that duplicate requests are handled safely. When you retry a request with the same idempotency key:

200 OK: If a payin with the same idempotency key already exists and no further work is needed for this request, the existing payin is returned.
201 Created: If no payin exists with the provided idempotency key, a new payin is created.
With auto_approve=true, an idempotency match that is still CREATED continues approve→initiate. A match in CANCELED or FAILED returns 409.

Success Responses

Status Code	Description
200	OK — An existing payin with the provided idempotency key was found and returned (idempotency recovery / already-advanced replay)
201	Created — The payin was created; with `auto_approve`, processing finished within this response for your request (`status` reflects the result).
202	Accepted — The payin was created (and approved when `auto_approve` is true). `status` in the body may still change; poll `GET /api/payins/{id}` until the payin reaches a terminal status.
207	Multi-Status — Payin was created (or already existed as `CREATED`) but approval failed. The response includes the payin data and a `warning`. The payin remains `CREATED`.

Error Responses

Status Code	Error Code	Description
400	VALIDATION_ERROR	The provided data failed validation
401	AUTHENTICATION_ERROR	Authentication credentials are invalid or missing
403	AUTHORIZATION_ERROR	You do not have permission to perform this action
404	PAYER_NOT_FOUND	The payer was not found or doesn’t belong to your entity
404	PAYMENT_METHOD_NOT_FOUND	The specified payment method was not found
409	IDEMPOTENCY_KEY_CONFLICT	Idempotency key matches an existing payin in a terminal failed or canceled state; use a new key
422	INVALID_PAYMENT_DETAILS	The payment details are invalid or incomplete
503	(see response body)	With `auto_approve`, the payin was created (and approved) but initiation hit a transient error. Retry the same create request after a short wait. The JSON body includes `error_code` and `message`.

Auto-approve behavior

When auto_approve=true, the API creates the payin (or continues from an idempotent CREATED match) and continues approval and async initiation as far as this request allows. You may receive 201, 202, 207, or 503 depending on outcome:

201 / 202: The payin id is always in the response. If you receive 202, poll GET /api/payins/{id} until status reaches a value you treat as final for your integration.
207: Creation succeeded but approval failed; read warning and status (still CREATED). Standalone approve returns 4xx for the same approval failure.
503: Transient error while starting async initiation—retry the create; use the response message (and error_code) for support and automation.

Creates a new payin to collect funds from a payer using their payment method. A payin represents an ACH debit transaction that pulls money from the payer's bank account. Supports both regular payins and subaccount payins (test entities only). **Request Body** | Field | Type | Required | Description | Validation Rules | |--------------------------|------|----------|-------------|------------------| | `payer_id` | UUID | Yes | ID of the payer from whom to collect funds. | Must be a valid UUID for an existing payer | | `amount_in_minor_units` | Integer | Yes | Amount in the smallest unit of the currency. For USD, this is cents (100 = $1.00). | Must be a positive whole number. | | `currency_code` | String | No | ISO 4217 currency code. Defaults to the source account's currency. | If supplied, must match a supported country and currency combination for debit. | | `rail` | String | No | Payment rail to use. Options: `standard_ach`, `same_day_ach`. Uses default if not provided. | Must be one of the supported ACH rails | | `payment_method_id` | UUID | No | ID of a specific payment method to use instead of the payer's default payment method. | Must be a valid UUID for an existing payment method belonging to the payer | | `subaccount_id` | UUID | No | ID of the subaccount to credit to (test entities only). When provided, the payin will be credited to the specified subaccount instead of the main account. | Must be a valid UUID for an existing subaccount belonging to the entity. Only available for sandbox/test entities. | | `auto_approve` | Boolean | No | If set to true, payin will automatically transition to approved and initiated state. | default: `false` | | `metadata` | Object | No | Arbitrary metadata as key-value pairs to store with the payin for your own reference. | Must be an object with string keys and string values. Maximum 50 keys, each key max 40 characters, each value max 500 characters, total size max 16KB. | **Examples:** - For USD, `amount_in_minor_units: 2500` is 2500 cents = $25.00 - For USD, `amount_in_minor_units: 10075` is 10075 cents = $100.75 **Response Body** | Field | Type | Description | |-------|------|-------------| | `id` | UUID | Unique identifier for the payin. | | `payer_id` | UUID | ID of the payer from whom funds are being collected. | | `subaccount_id` | UUID | ID of the subaccount this payin is attributed to. Null if attributed to main account. | | `status` | String | Current status of the payin (`created`, `canceled`, `approved`, `initiated`, `debited`, `settled`, `failed`) | | `amount_in_minor_units` | Integer | The payin amount in the smallest unit of the currency. For USD, cents (100 = $1.00). | | `amount_in_cents` | Integer | Deprecated alias for `amount_in_minor_units`. | | `currency_code` | String | ISO 4217 currency code of the destination account. | | `country_code` | String | ISO 3166-1 alpha-2 country code of the destination account. | | `rail` | String | Payment rail used (standard_ach, same_day_ach) | | `payin_metadata` | Object | Contains payment method details and payer information (sensitive data is masked) | | `client_metadata` | Object | Arbitrary metadata as key-value pairs that were provided when creating the payin | | `status_recorded_at` | DateTime | Timestamp when the current status was recorded | | `created_at` | DateTime | Timestamp when the payin was created | | `updated_at` | DateTime | Timestamp when the payin was last updated | **Note:** Use `amount_in_minor_units` in request bodies. The `amount_in_cents` field is deprecated and retained in responses for backward compatibility. **Idempotency Key** You can include an `Idempotency-Key` header to ensure that duplicate requests are handled safely. When you retry a request with the same idempotency key: - **200 OK**: If a payin with the same idempotency key already exists and no further work is needed for this request, the existing payin is returned. - **201 Created**: If no payin exists with the provided idempotency key, a new payin is created. - With **`auto_approve=true`**, an idempotency match that is still **`CREATED`** continues approve→initiate. A match in **`CANCELED`** or **`FAILED`** returns **409**. **Success Responses** | Status Code | Description | |-------------|-------------| | 200 | OK — An existing payin with the provided idempotency key was found and returned (idempotency recovery / already-advanced replay) | | 201 | Created — The payin was created; with **`auto_approve`**, processing finished within this response for your request (**`status`** reflects the result). | | 202 | Accepted — The payin was created (and approved when **`auto_approve`** is true). **`status`** in the body may still change; poll **`GET /api/payins/{id}`** until the payin reaches a terminal status. | | 207 | Multi-Status — Payin was created (or already existed as **`CREATED`**) but **approval** failed. The response includes the payin data and a **`warning`**. The payin remains **`CREATED`**. | **Error Responses** | Status Code | Error Code | Description | |-------------|------------|-------------| | 400 | VALIDATION_ERROR | The provided data failed validation | | 401 | AUTHENTICATION_ERROR | Authentication credentials are invalid or missing | | 403 | AUTHORIZATION_ERROR | You do not have permission to perform this action | | 404 | PAYER_NOT_FOUND | The payer was not found or doesn't belong to your entity | | 404 | PAYMENT_METHOD_NOT_FOUND | The specified payment method was not found | | 409 | IDEMPOTENCY_KEY_CONFLICT | Idempotency key matches an existing payin in a terminal failed or canceled state; use a new key | | 422 | INVALID_PAYMENT_DETAILS | The payment details are invalid or incomplete | | 503 | (see response body) | With **`auto_approve`**, the payin was created (and approved) but initiation hit a **transient error**. **Retry** the same create request after a short wait. The JSON body includes `error_code` and `message`. | **Auto-approve behavior** When **`auto_approve=true`**, the API creates the payin (or continues from an idempotent **`CREATED`** match) and continues approval and async initiation as far as this request allows. You may receive **201**, **202**, **207**, or **503** depending on outcome: - **201** / **202**: The payin id is always in the response. If you receive **202**, poll **`GET /api/payins/{id}`** until **`status`** reaches a value you treat as final for your integration. - **207**: Creation succeeded but **approval** failed; read **`warning`** and **`status`** (still **`CREATED`**). Standalone approve returns **4xx** for the same approval failure. - **503**: Transient error while starting async initiation—**retry** the create; use the response **`message`** (and **`error_code`**) for support and automation.

Authentication

x-api-keystring

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

Request

This endpoint expects an object.

payer_idstringRequiredformat: "uuid"

ID of the payer

amount_in_minor_unitsinteger or nullOptional

Amount in the currency’s minor units (e.g. cents for USD).

currency_codeenumOptional

Currency code

railstring or nullOptional

Payment rail (standard_ach, same_day_ach). Uses default if not provided.

payment_method_idstring or nullOptionalformat: "uuid"

Specific payment method ID (uses default if not provided)

auto_approvebooleanOptionalDefaults to false

Whether to automatically approve and initiate the payin

metadatamap from strings to any or nullOptional

Client metadata

subaccount_idstring or nullOptionalformat: "uuid"

Subaccount to credit to (test entities only)

scheduled_datedate or nullOptional

Calendar day to release the transfer in its schedule timezone (currently America/New_York). Omitted for immediate. Not the beneficiary credit date. Resolved to 09:00 in that timezone.

amount_in_centsinteger or nullOptionalDeprecated

Deprecated. Use amount_in_minor_units instead. Still accepted and returned for backward compatibility.

Response

Payin retrieved successfully (idempotency retry)

Errors

409

Conflict Error

503

Service Unavailable Error