Approve single payin

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "payer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "amount_in_minor_units": 2500,
    "currency_code": "USD",
    "rail": "same_day_ach",
    "status": "initiated",
    "status_recorded_at": "2024-01-15T09:30:00Z",
    "payin_metadata": {
      "invoice_number": "INV-20240115-001",
      "customer_reference": "CUST-789456"
    },
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:45:00Z",
    "amount_in_cents": 2500,
    "client_metadata": {
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
    }
  },
  "warning": null
}

Approves a single payin for processing. The payin must be in CREATED status.

Response body

Field	Type	Description
`data`	Object	The payin object (`status` reflects the state at response time)
`warning`	String	Present on 207 when initiation had a recoverable issue

Success responses

Status Code	Description
201	The payin was approved and processing continued; `data.status` reflects the outcome of this request.
202	The request was accepted and `data` includes the payin, but `data.status` may still change. Poll `GET /api/payins/{id}` until the payin reaches a terminal status.
207	The payin was approved but initiation did not complete successfully; see `warning` and `data.status`.

Error and retry responses

Status Code	Error code	Description
400	`INVALID_STATUS`	The payin is not in CREATED status and cannot be approved.
401	`AUTHENTICATION_ERROR`	Authentication credentials are invalid or missing.
403	`AUTHORIZATION_ERROR`	You do not have permission to perform this action.
404	`PAYIN_NOT_FOUND`	Payin not found or does not belong to your entity.
503	(see response body)	Transient error—bank initiation did not complete for this request. Retry the same approve call after a short wait. The JSON body includes `error_code` and `message` for logging and automation.

Notes

Treat 202 like any accepted operation: use the returned id and poll until status stabilizes.
503 is for retries, not a final business outcome for the transfer.

Approves a single payin for processing. The payin must be in **CREATED** status. **Response body** | Field | Type | Description | |-------|------|-------------| | `data` | Object | The payin object (`status` reflects the state at response time) | | `warning` | String | Present on **207** when initiation had a recoverable issue | **Success responses** | Status Code | Description | |-------------|-------------| | **201** | The payin was approved and processing continued; **`data.status`** reflects the outcome of this request. | | **202** | The request was accepted and **`data`** includes the payin, but **`data.status`** may still change. Poll **`GET /api/payins/{id}`** until the payin reaches a terminal status. | | **207** | The payin was approved but initiation did not complete successfully; see **`warning`** and **`data.status`**. | **Error and retry responses** | Status Code | Error code | Description | |-------------|------------|-------------| | **400** | `INVALID_STATUS` | The payin is not in **CREATED** status and cannot be approved. | | **401** | `AUTHENTICATION_ERROR` | Authentication credentials are invalid or missing. | | **403** | `AUTHORIZATION_ERROR` | You do not have permission to perform this action. | | **404** | `PAYIN_NOT_FOUND` | Payin not found or does not belong to your entity. | | **503** | (see response body) | **Transient error**—bank initiation did not complete for this request. **Retry** the same approve call after a short wait. The JSON body includes `error_code` and `message` for logging and automation. | **Notes** - Treat **202** like any accepted operation: use the returned id and **poll** until status stabilizes. - **503** is for **retries**, not a final business outcome for the transfer.

Authentication

x-api-keystring

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

Path parameters

payin_idstringRequiredformat: "uuid"

Response

Payin approved and initiated successfully

dataobject or null

Response model for payin operations.

warningstring or null

Errors

404

Not Found Error

503

Service Unavailable Error

Approves a single payin for processing. The payin must be in CREATED status.

Response body

Field	Type	Description
`data`	Object	The payin object (`status` reflects the state at response time)
`warning`	String	Present on 207 when initiation had a recoverable issue

Success responses

Status Code	Description
201	The payin was approved and processing continued; `data.status` reflects the outcome of this request.
202	The request was accepted and `data` includes the payin, but `data.status` may still change. Poll `GET /api/payins/{id}` until the payin reaches a terminal status.
207	The payin was approved but initiation did not complete successfully; see `warning` and `data.status`.

Error and retry responses

Status Code	Error code	Description
400	`INVALID_STATUS`	The payin is not in CREATED status and cannot be approved.
401	`AUTHENTICATION_ERROR`	Authentication credentials are invalid or missing.
403	`AUTHORIZATION_ERROR`	You do not have permission to perform this action.
404	`PAYIN_NOT_FOUND`	Payin not found or does not belong to your entity.
503	(see response body)	Transient error—bank initiation did not complete for this request. Retry the same approve call after a short wait. The JSON body includes `error_code` and `message` for logging and automation.

Notes

Treat 202 like any accepted operation: use the returned id and poll until status stabilizes.
503 is for retries, not a final business outcome for the transfer.

$	curl -X POST https://api.useroot.com/api/payins/payin_id/approve \
>	-H "x-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{}'