API Reference

Payins API

View as Markdown

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:

StatusDescription
initiatedThe payin has been created and sent to the banking partner, funds are in transit.
settledThe payin has been successfully completed and funds have been received.
failedThe 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

RailNameDescriptionSLA
same_day_achSame-Day ACHExpedited ACH transferFunds typically available same business day if initiated before 1 PM ET
standard_achStandard ACHStandard ACH transferFunds 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.