Skip to navigation

Create a new payin

View as Markdown

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

FieldTypeRequiredDescriptionValidation Rules
payer_idUUIDYesID of the payer from whom to collect funds.Must be a valid UUID for an existing payer
amount_in_minor_unitsIntegerYesAmount in the smallest unit of the currency. For USD, this is cents (100 = $1.00).Must be a positive whole number.
currency_codeStringNoISO 4217 currency code. Defaults to the source account’s currency.If supplied, must match a supported country and currency combination for debit.
railStringNoPayment rail to use. Options: standard_ach, same_day_ach. Uses default if not provided.Must be one of the supported ACH rails
payment_method_idUUIDNoID 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_idUUIDWhen the main account has any subaccount, or the config is a Root FBOID of the subaccount to credit. Required once the main account has any subaccount, and always on Root FBO.Must be a valid UUID for an existing subaccount belonging to the entity.
auto_approveBooleanNoIf set to true, payin will automatically transition to approved and initiated state.default: false
metadataObjectNoArbitrary 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

FieldTypeDescription
idUUIDUnique identifier for the payin.
payer_idUUIDID of the payer from whom funds are being collected.
subaccount_idUUIDID of the subaccount this payin is attributed to. Null if attributed to main account.
statusStringCurrent status of the payin (created, canceled, approved, initiated, debited, settled, failed)
amount_in_minor_unitsIntegerThe payin amount in the smallest unit of the currency. For USD, cents (100 = $1.00).
amount_in_centsIntegerDeprecated alias for amount_in_minor_units.
currency_codeStringISO 4217 currency code of the destination account.
country_codeStringISO 3166-1 alpha-2 country code of the destination account.
railStringPayment rail used (standard_ach, same_day_ach)
payin_metadataObjectContains payment method details and payer information (sensitive data is masked)
client_metadataObjectArbitrary metadata as key-value pairs that were provided when creating the payin
status_recorded_atDateTimeTimestamp when the current status was recorded
created_atDateTimeTimestamp when the payin was created
updated_atDateTimeTimestamp 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 (so after you cancel a payin, reusing its key with auto_approve=true returns 409; use a new key). With auto_approve=false, a match always returns the existing payin with 200, whatever its status.

Success Responses

Status CodeDescription
200OK — An existing payin with the provided idempotency key was found and returned (idempotency recovery / already-advanced replay)
201Created — The payin was created; with auto_approve, processing finished within this response for your request (status reflects the result).
202Accepted — 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.
207Multi-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 CodeError CodeDescription
400VALIDATION_ERRORThe provided data failed validation
401AUTHENTICATION_ERRORAuthentication credentials are invalid or missing
403AUTHORIZATION_ERRORYou do not have permission to perform this action
404PAYER_NOT_FOUNDThe payer was not found or doesn’t belong to your entity
404NOT_FOUNDThe payer has no default payment method (and no payment_method_id was provided). details.reason is no_default_payment_method with party_type, party_id, and legacy payor_id.
404PAYMENT_METHOD_NOT_FOUNDThe specified payment method was not found
409IDEMPOTENCY_KEY_CONFLICTIdempotency key matches an existing payin in a terminal failed or canceled state; use a new key
422INVALID_PAYMENT_DETAILSThe payment details are invalid or incomplete
422subaccount_id_requiredsubaccount_id was omitted, but the main account has a subaccount or the bank config is a Root FBO. Resend with subaccount_id.
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). See Handling a 207 below.
  • 503: Transient error while starting async initiation—retry the create; use the response message (and error_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 verified or 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:

  1. Find the reason: call POST /api/payins/{id}/approve. It runs the same checks and returns a 4xx with a specific error_code and message.
  2. Fix the cause. If the payment method is pending verification, wait for the payment_method.verified webhook.
  3. Approve the payin: call POST /api/payins/{id}/approve, or resend the create request with the same Idempotency-Key and auto_approve=true. The resend does not create a second payin; it continues approval of the existing one.
  4. If you no longer want the payin, cancel it with DELETE /api/payins/{id}. After a cancel, a create with the same key and auto_approve=true returns 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

x-api-keystring

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

Headers

Idempotency-Keystring or nullOptional
Unique key to prevent duplicate requests

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
Allowed values:
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. 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.

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