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.

Creating a bank account

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

FieldDescription
nameOnAccountFull name on bank account
routingNumberBank account routing number. For testing, enter any valid routing number. For example, 074000010.
accountNumberBank account number
typeBank account type (CHECKING or SAVINGS)
ownerTypeBank account owner type (BUSINESS or PERSONAL)
bankNameBank name. Set this field as a nickname for your bank account.

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

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.

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.

FieldDescription
bankAccountIdBILL-generated ID of the bank account. The value begins with bac.
depositAmountVerify deposit amount. Enter an amount between 0.01 and 0.99.

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.