ACH Guide
Follow this guide to link customer bank accounts and start creating ACH payments and payouts.
Circle has partnered with Plaid to allow your integration to:
- Receive ACH payments that settle in USDC
- Send ACH payouts to customer bank accounts
With Plaid Link, your customers can securely authenticate with their bank without sharing login credentials to you or Circle. Plaid Link offers a robust, drop-in client-side integration that returns access tokens that allow you and Circle to authenticate requests to Plaid's APIs. Using those APIs, Circle is able to initiate payments and payouts on your customer's behalf.
Learn more about Plaid Link, and how it supports all modern web browsers as well as iOS, Android, and mobile web.
Integration Overview
Circle's payments and payouts API endpoints work seamlessly across cards, wires, and ACH rails. When creating an ACH payment, simply specify the source
as an ACH account. For payouts, set the destination
to the ACH account you'd like to receive funds.
In this guide we'll walk through the steps needed to create your first ACH payment or payout:
- Obtain a processor token from Plaid
- Create a linked bank account on Circle using the token
- Create a payment or payout
Obtain a Processor Token
To use ACH payments and payouts, you'll need a developer account with Plaid and integrate Plaid Link and their APIs.
In order for Circle to communicate with Plaid about the customer's bank account, you'll need to obtain a processor_token
from Plaid specifically for Circle, and share that with us.
Follow Plaid's Circle Integration Guide for a step-by-step flow. To summarize, what you'll do is:
- Integrate with Plaid Link, which allows your customer to log into their bank and return you a
public_token
. - Use Plaid's API to exchange the
public_token
for anaccess_token
. - Use the
access_token
with Plaid's API to create a Circle-specificprocessor_token
.
The access_token
is for your service's own use, and the processor_token
is what you share with Circle. It allows Circle to access information about the customer's bank account, which we'll need to initiate payments and payouts.
Keeping Tokens Updated
The processor token you provide to Circle, as well as your access token, can expire over time and require your user to re-authenticate. Scenarios that could trigger this include password changes and modifications to security/MFA settings.
Plaid provides a simple process to refresh the authentication information through their update mode. After you direct your user to your app to go through Plaid Link and re-authenticate, the existing access_token
(that you have) and processor_token
(that Circle has) are automatically refreshed without requiring any updates through our APIs.
Keeping these tokens up to date is an important part of making sure balance checks function properly, which keep your ACH returns and their corresponding fees as infrequent as possible.
Processor Tokens in Sandbox
While Plaid offers the ability to generate processor_tokens
in their sandbox environment, Circle's sandbox environment does not use these tokens. Instead, we have set up a separate sandbox endpoint that you can use to generate a mock processorToken
to use during development.
To create a mock processorToken
, use our Create a mock ACH account endpoint with details about the mock account you'd like to create.
{
"account": {
"accountNumber": "123456789",
"routingNumber": "011000028",
"description": "My Bank Account"
},
"balance": {
"amount": "100.00",
"currency": "USD"
}
}
The accountNumber
can be any string you'd like, but the routingNumber
should be one of the valid routing numbers listed in the documentation.
The API response will include a processorToken
that you will use in the next step.
{
"processorToken": "processor-sandbox-circle-b6360275-40ad-423a-b7c5-aaf7007cd164",
..
}
Create a Linked Bank Account
Once you have either a processor_token
from Plaid's production environment or a processorToken
from Circle's sandbox, you're ready to link the account with Circle.
- Set
plaidProcessorToken
in the Create a bank account (ACH) endpoint to create a link to this account on Circle. - Linked bank accounts start with
status: pending
while we verify the token and fetch the account information. Subscribe to notifications or poll the bank account object you just created to find out when the status changes tocomplete
. - Before creating a payment or payout with an ACH account, make sure it has
status: complete
.
For those that have access to Plaid's Identity product, you can easily get
billingDetails
information with their/identity/get
endpoint and pre-fill a form for your customer to confirm its accuracy.
Create a Payment or Payout
ACH accounts created using the /v1/banks/ach
endpoint can be used for both payments and payouts.
Important
When creating ACH payments, you will need to obtain ACH authorization from your end users. This is to comply with NACHA (National Automated Clearing House Association) regulations, and helps you avoid payment reversals.
Learn more about ACH Authorization.
When creating a payment, simply specify the ACH account as the source
and set verification
(which is to used for card payments) to none
:
// POST /v1/payments
{
...,
"verification": "none",
"source": {
"id": "20d8445a-b5f8-437b-ba62-c3b44d554335",
"type": "ach"
}
}
When creating a payout specify the account as the destination
:
// POST /v1/payouts
{
...,
"destination": {
"id": "20d8445a-b5f8-437b-ba62-c3b44d554335",
"type": "ach"
}
}
Balance Checks
When you create an ACH payment in the live environment, Circle will use Plaid's Balance product to verify the real-time account balance of the ACH account. If the available balance is not sufficient to cover the payment amount, the payment will fail. This check carries a small cost that will be billed to you directly, by Plaid. Please refer to your Plaid account for exact rates.
This check is a necessary step in order to minimize the likelihood of returns due to insufficient funds, which incur significantly higher fees for you and your customers. Circle's real-time balance check also happens much more quickly (minutes versus days), giving customers an improved user experience in the event of insufficient funds.
Payment and Payout Processing
To follow the status of payments and be notified when funds settle, visit our guide on Post-Payments Processing.
Payouts follow a similar pattern, and you can subscribe to notifications or poll the payout object to look for status: complete
.
Additional Info
- For both payments and payouts, there is a per-transaction limit of $25,000.
- Learn about settlement times and cut-offs to better understand when funds from payments will settle and when payouts will reach customer bank accounts.
Updated 8 months ago