ACH Overview

ACH transactions can be originated via the Create ACH Transfer endpoint. Please note that all ACH transactions created are originations, meaning that the ACH file is generated by your partner bank and sent to an external bank for processing. ACH transactions fall into one of two categories:

• ACH Push Origination
  • Generates a request to 'push' funds to an external account.
  • Your customer's account will be debited and the external account will be credited.
  • Indicated by 'C' for debitCreditIndicator in the /createAchTransfer call.
• ACH Pull Origination
  • Generates a request to 'pull' funds from an external account into your customer's account.
  • Your customer's account will be credited and the external account will be debited.
  • Indicated by 'D' for debitCreditIndicator in the /createAchTransfer call.
  • Your partner bank will typically require a set number of 'hold days' before ACH pull originations post to your customer's account to reduce returns and mitigate fraud.

Creating ACH Accounts

Before an ACH transaction can be initiated, you must create an ACH account to associate with the given customer (see Create ACH Account).

After creating the ACH account, you will receive an achAccountId which will serve as the unique identifier for the external account. Use this ID when calling the Create ACH Transfer endpoint.

There are two ways to create an ACH account:

📘

Please note

Your partner bank will likely limit the number of ACH account connections per customer account to limit fraud. ACH accounts can be removed via Remove ACH Account.

Using Linked Institutions for ACH

Spidr's Linked Institutions feature allows users to connect their external bank accounts via Plaid. Benefits for ACH:

• Eliminates manual routing/account number entry (and the errors that come with it)
• Validates account ownership via the provider
• Enables balance checks before ACH pull originations (via checkBalance parameter)
• Does not require your system to handle or store raw account numbers

Linked Institution → ACH Account

After a user completes the Linked Institutions flow (see the setup guide for full integration steps), you receive a linkedInstitutionAccountId for each connected account. Pass this ID — in place of routing/account numbers — when calling Create ACH Account:

POST /v1/achaccount/create
{
  "accountId": "<spidr_account_id>",
  "linkedInstitutionAccountId": "<linked_institution_account_id>"
}

Spidr resolves the account details from the linked institution record; no routing or account number is needed in the request. The returned achAccountId is then used for all subsequent Create ACH Transfer calls.

📘

Balance checks

When calling Create ACH Transfer, pass checkBalance: true to verify sufficient funds in the linked external account before the transfer is created. You can also pass minimumRemainingBalance to enforce a floor on the external account's post-transaction balance. Balance check availability for linked institution accounts is contingent on your product's configuration.