Bank account setup (v3 API)

Bank account setup in your BILL organization with the BILL v3 API is a two-step process.

• Create a bank account with POST /v3/funding-accounts/banks
• Verify the bank account with POST /v3/funding-accounts/banks/{bankAccountId}/verify

📘

NOTE

You can also set up a bank account with the BILL web app. See Bank account setup (BILL web app) for more information.

Money movement to and from live bank accounts is not available in the API sandbox environment. When you set up a test bank account in sandbox, you can create and test payments.

Bank accounts best practices

We recommend that you follow the best practices checklist when setting up bank accounts with the BILL v3 API.

1. Test with different account numbers: When you create a test bank account, use different test routingNumber and accountNumber combinations. Avoid using the same numbers across different test BILL organizations.
2. Complete bank account verification: After you create a test bank account, complete the bank account verification step. This helps with better managing your test bank accounts.

Creating a bank account

In your POST /v3/funding-accounts/banks request, set the required fields.

See the /v3/funding-accounts/banks API for more information.

Sample request

In this cURL example, a bank account is set up with the specified details. The new bank account is created in the BILL organization that the currently signed-in user has access to.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/funding-accounts/banks' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "nameOnAccount": "Noodle Soupsmith",
  "routingNumber": "074000010",
  "accountNumber": "111222333",
  "type": "CHECKING",
  "ownerType": "BUSINESS",
  "bankName": "Chase"
}'

Response

In the response, a BILL-generated bank account id is available. The value begins with bac. You can use this bank account id for other BILL operations, such as setting it as a funding account source when you create a payment with POST /v3/payments. See Payments for more information.

{
  "id": "{bankaccount_id}",
  "archived": true,
  "status": "PENDING",
  "createdBy": "{user_id}",
  "routingNumber": "074000010",
  "accountNumber": "*****2333",
  "nameOnAccount": "Noodle Soupsmith",
  "type": "CHECKING",
  "ownerType": "BUSINESS",
  "bankName": "Chase",
  "default": {
    "payables": false,
    "receivables": false
  },
  "createdTime": "2024-12-16T23:15:23.127+00:00",
  "updatedTime": "2024-12-16T23:15:23.127+00:00"
}

❗️

IMPORTANT

In the production environment, when you create a bank account with the API, BILL sends a test ACH payment to the bank account to confirm whether the account details are accurate.

Use this ACH payment value to verify your bank account with POST /v3/funding-accounts/banks/{bankAccountId}/verify.

In the response, three fields are set to their default values.

• The bank account status is set as PENDING. You can verify the bank account with POST /v3/funding-accounts/banks/{bankAccountId}/verify.
• The payables and receivables values are set as false. To update these values, update the bank account with PATCH /v3/funding-accounts/banks/{bankAccountId}.

See the /v3/funding-accounts/banks API for more information.

Verifying a bank account

In your POST /v3/funding-accounts/banks/{bankAccountId}/verify request, set the required fields.

When you create a bank account, BILL sends a test ACH payment to the bank account to confirm whether the account details are accurate. Enter the test amount as the depositAmount value in your POST /v3/funding-accounts/banks/{bankAccountId}/verify request.

❗️

IMPORTANT

When you create a bank account with the API in the production environment, you must complete bank account verification before the account can be used for other BILL operations.

In the sandbox environment, set depositAmount as 0.50 to complete bank account verification.

See the /v3/funding-accounts/banks/{bankAccountId}/verify API for more information.

Sample request

In this cURL example, the bank account verification is initiated. In the request, depositAmount is set as the test ACH payment sent by BILL when the bank account was created.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/funding-accounts/banks/{bankAccountId}/verify' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "depositAmount": 0.50
}'

Response

In the response, the bank account verification status is available.

{
  "verified": true
}

The bank account status is set as VERIFIED when BILL is able to verify the depositAmount value. When BILL cannot verify the bank account after three attempts, you cannot use the bank account. At that point, use another bank account or create a bank account with POST /v3/funding-accounts/banks.

See the /v3/funding-accounts/banks/{bankAccountId}/verify API for more information.