Add a Bank Account

This guide outlines how to add and verify bank accounts using the Checkbook API. Checkbook offers two primary methods for verification: microdeposits and instant account verification.

In addition to adding and verifying an account via the API, bank accounts can also be added on the Checkbook dashboard .

Microdeposit Verification

For microdeposit verification, Checkbook will initiate two small deposits to the target bank account. The amounts of these small deposits must then be verified to show that our customer has access to the bank account.

Create a bank account

First you’ll need to create a bank account in the Checkbook system by providing the routing and account number via our add a bank endpoint. Once this step is successfully completed, you’ll have an unverified account linked to your Checkbook profile.

Things you need

account: The bank account number

routing: The 9 digit routing number of the account

type: BUSINESS, PERSONAL or CHECKING to indicate the appropriate account type


curl -X POST \
  -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "12345678",
    "routing": "322271627",
    "type": "BUSINESS"
  }' \
  https://demo.checkbook.io/v3/account/bank

Response:


{
  "account": "5678",
  "date": "2025-04-29 07:36:57",
  "id": "efdbaaaa17b244abba084e6c2ccfc990",
  "routing": "322271627",
  "status": "DEPOSIT_ONLY",
  "type": "BUSINESS"
}

Initiate the microdeposit transactions

When creating the bank account, Checkbook does not automatically initiate the microdeposit verification process. We’ll now release the microdeposits using the release endpoint using the ID returned the previous step:


curl -X POST \
  -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "efdbaaaa17b244abba084e6c2ccfc990"
  }' \
  https://demo.checkbook.io/v3/account/bank/release

Upon success, the status of the bank account will move from DEPOSIT_ONLY to PENDING, and Checkbook will initiate the two small credits to the bank accounts. Customers should expect to see these show up in their bank account 1 business day later.

Verify the microdeposit transactions

Once the transactions have arrived, the recipient will need to verify the amounts of the microdeposits. To do this, the verify endpoint is used to submit the amounts of the transactions:


 
curl -X POST \
  -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" \
  -H "Content-Type: application/json" \
  -d '{
	  "account": "efdbaaaa17b244abba084e6c2ccfc990",
	  "amount_1": 0.07,
	  "amount_2": 0.15
	}' \
  https://demo.checkbook.io/v3/account/bank/verify

A successful verification will result in the status of the bank account moving from PENDING to VERIFIED, which allows the customer to use this account for sending funds.

💡

Tip

In the sandbox environment, the microdeposit amounts will always be 0.07 and 0.15

Instant Account Verification

Unlike microdeposit verification, which takes place over multiple business days, instant account verification allows bank accounts to be verified within seconds.

⚠️

Warning

Most banks support instant account verification, but instant account verification is not supported by all banking institutions.

Checkbook has partnered with Plaid to provide instant account verification services to the largest number of institutions possible. Before continuing with the rest of this section, you’ll need to sign up for a Plaid account.

Get a Plaid access token

The Plaid Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange Plaid API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you would like the user to specify only a single account to link so you know which account to use with Checkbook, set Select Account to “enabled for one account” in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Create a Checkbook processor token

Once you have identified the account you will use, send the access_token and account_id property of the account to Plaid via the /processor/token/create Plaid API endpoint in order to create a Checkbook processor_token.

You can create Checkbook processor_tokens in all three API environments:

Sandbox (https://sandbox.plaid.com ): test simulated users
Development (https://development.plaid.com ): test live users
Production (https://production.plaid.com ): production environment for when you are ready to go live and have valid Checkbook Production credentials

Example


# Exchange token
curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "[Plaid Client ID]",
    "secret": "[Plaid secret]",
    "public_token": "[Public token]"
  }'
# Create a processor token for a specific account id.
curl -X POST https://sandbox.plaid.com/processor/token/create \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "PLAID_CLIENT_ID",
    "secret": "PLAID_SECRET",
    "access_token": "ACCESS_TOKEN",
    "account_id": "ACCOUNT_ID",
    "processor": "checkbook"
  }'

Add a bank account

Retrieve the bank account(s) associated with the Plaid token. Once you have the Checkbook processor_token, you can use it to securely retrieve account and routing numbers from Plaid. Just call the POST /v3/bank/iav/plaid endpoint with the processor_token.


curl --request POST \\
	--url <https://sandbox.checkbook.io/v3/account/bank/iav/plaid> \\
	--header 'Authorization: sender_key:sender_secret' \\
	--header 'accept: application/json' \\
	--header 'content-type: application/json' \\
	--data '{ "processor_token": "processor-sandbox-b9282007-a6b1-47ef-9075-a11c684b6a70" }'

Response:


{
  "accounts": [
    {
      "account": "string",
      "name": "string",
      "routing": "string"
    }
  ]
}

Now that we’ve retrieved the banking information, we need to add it to the Checkbook system. Make sure to use the same user’s credentials when adding the bank account when calling [POST /v3/account/bank]. If successful, the bank status should be VERIFIED.


curl --request POST \\
	--url <https://sandbox.checkbook.io/v3/account/bank> \\
	--header 'Authorization: sender_key:sender_secret' \\
	--header 'accept: application/json' \\
	--header 'content-type: application/json' \\
	--data '{
		"type": "CHECKING",
		"account": "-<acct last 4>",
		"routing": "<routing>"
	}'

Response:


{
  "account": "-0000",
  "billing": false,
  "date": "2024-02-10 00:22:40",
  "default": false,
  "id": "d6c299de6d3441208ef42b37176d242d",
  "name": null,
  "routing": "011401533",
  "status": "VERIFIED",
  "type": "CHECKING"
}