Circle has partnered with Plaid to allow your integration to:

1. Receive ACH payments that settle in USDC
2. 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:

1. Obtain a processor token from Plaid
2. Acquire the bank account type (retail bank or business bank) from your customer.
3. Create a linked bank account on Circle using the token and bank account type.
4. 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:

1. Integrate with Plaid Link, which allows your customer to log into their bank and return you a public_token.
2. Use Plaid's API to exchange the public_token for an access_token.
3. Use the access_token with Plaid's API to create a Circle-specific processor_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.

1. Set plaidProcessorToken in the Create a bank account (ACH) endpoint to create a link to this account on Circle.
2. 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 to complete.
3. 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.