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.
- Test with different account numbers: When you create a test bank account, use different test
routingNumber
andaccountNumber
combinations. Avoid using the same numbers across different test BILL organizations. - 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.
Field | Description |
---|---|
nameOnAccount | Full name on bank account |
routingNumber | Bank account routing number. For testing, enter any valid routing number. For example, 074000010 . |
accountNumber | Bank account number |
type | Bank account type (CHECKING or SAVINGS ) |
ownerType | Bank account owner type (BUSINESS or PERSONAL ) |
bankName | Bank 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
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 asPENDING
. You can verify the bank account withPOST /v3/funding-accounts/banks/{bankAccountId}/verify
. - The
payables
andreceivables
values are set asfalse
. To update these values, update the bank account withPATCH /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
as0.50
to complete bank account verification.
Field | Description |
---|---|
bankAccountId | BILL-generated ID of the bank account. The value begins with bac . |
depositAmount | Verify 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.
Updated about 1 month ago