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 payins to the main account and to subaccounts, in both test and live. subaccount_id is required when the main account has any subaccount, or when the bank config is a Root FBO.
Request Body
Examples:
- For USD,
amount_in_minor_units: 2500is 2500 cents = $25.00 - For USD,
amount_in_minor_units: 10075is 10075 cents = $100.75
Response Body
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 stillCREATEDcontinues approve→initiate. A match inCANCELEDorFAILEDreturns 409 (so after you cancel a payin, reusing its key withauto_approve=truereturns 409; use a new key). Withauto_approve=false, a match always returns the existing payin with 200, whatever its status.
Success Responses
Error Responses
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}untilstatusreaches a value you treat as final for your integration. - 207: Creation succeeded but approval failed; read
warningandstatus(stillCREATED). See Handling a 207 below. - 503: Transient error while starting async initiation—retry the create; use the response
message(anderror_code) for support and automation.
Handling a 207
A 207 is returned only by create with auto_approve=true. The payin was created (the id is in the body), but the synchronous approval checks did not pass, so the payin stays CREATED. Nothing was sent to the bank, and no funds moved. The warning field says that approval failed. It does not give the reason.
Common causes:
- The payer’s payment method is no longer
verifiedor active (for example, its verification status changed or it was deleted after the payin was created). - The amount is outside the limits for the selected rail.
What to do:
- Find the reason: call
POST /api/payins/{id}/approve. It runs the same checks and returns a 4xx with a specificerror_codeandmessage. - Fix the cause. If the payment method is pending verification, wait for the
payment_method.verifiedwebhook. - Approve the payin: call
POST /api/payins/{id}/approve, or resend the create request with the sameIdempotency-Keyandauto_approve=true. The resend does not create a second payin; it continues approval of the existing one. - If you no longer want the payin, cancel it with
DELETE /api/payins/{id}. After a cancel, a create with the same key andauto_approve=truereturns 409.
Do not create a new payin with a new key to work around a 207. The first payin still exists in CREATED until you approve or cancel it.
Authentication
RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.
Headers
Request
Amount in the currency’s minor units (e.g. cents for USD).
Payment rail (standard_ach, same_day_ach). Uses default if not provided.
Specific payment method ID (uses default if not provided)
Subaccount to credit. Required when the main account has any subaccount, or when the bank config is a Root FBO; otherwise omit to credit the main account. Missing when required returns 422 subaccount_id_required.
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.
Deprecated. Use amount_in_minor_units instead. Still accepted and returned for backward compatibility.
Response
Payin retrieved successfully (idempotency retry)