Usage Info

This method establishes a relationship between a Bank Account and a Business entity, specifying the purposes the account serves for the business (such as primary operations, fees, settlements). Use this method when adding new financial accounts to a business profile.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
business_id	string	Yes	The Business to add this Owner to.
business_bank_account	object	No	The business_bank_account parameter defined in the table below.

Business Bank Account Parameters

Parameter	Type	Required	Description
bank_account_id	string	Yes	The Bank Account to be added to the Business.
bank_account_purposes	array	No	The purpose(s) of the bank account in the business. Must be one or more of the BANK_ACCOUNT_PURPOSES.

Example

{
  "business_id": "b_7eobHllxknr7mfqbjnX2Pp",
  "business_bank_account": {
    "bank_account_id": "ba_6zNzQZHSf26V83BO3uW6dS",
    "bank_account_purposes": [
      "PRIMARY",
      "FEES",
      "SETTLEMENT"
    ]
  }
}

Response

Data

Parameter	Type	Description
business_bank_account	object	The business_bank_account parameter defined in the table below.

Business Bank Account Parameters

Parameter	Type	Description
business_bank_account_id	string	The identifier for the Business Bank Account just created.

Example

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_3S6w6VfAnOG0QtdrdMCmaz",
    "version": "2025-03-24"
  },
  "data": {
    "business_bank_account": {
      "business_bank_account_id": "bba_79HaMs4zgYfilF3xQuJy3J"
    }
  }
}

Errors

Error Code	HTTP Code	Possible Cause
ACCOUNT_CONFIGURATION_VIOLATION	400	Account configuration rule violations are described below.
BAD_REQUEST	400	Required parameters not provided. Invalid values provided. Enum value provided does not correspond to an available type.
ENTITY_NOT_FOUND	400	The `business_id` or `bank_account_id` provided does not exist.
SYSTEM_RULE_VIOLATION	400	System rule violations are described below.

Account Configuration Violations

When a ACCOUNT_CONFIGURATION_VIOLATION error occurs, the response will include additional entity_type and sub_code fields to provide more specific information:

Entity Type	Sub-code	Description
Business	MAX_BANK_ACCOUNT_LIMIT	The maximum number of bank accounts allowed per Business has been reached. No additional bank accounts can be added.

System Rule Violations

When a SYSTEM_RULE_VIOLATION error occurs, the response will include additional entity_type and sub_code fields to provide more specific information:

Entity Type	Sub-code	Description
Business	DUPLICATE_BANK_ACCOUNT_ASSOCIATION	The Bank Account is already associated with this Business entity.
Business	SINGLE_PRIMARY_BANK_ACCOUNT	A Business can only have one bank account designated as PRIMARY. Another bank account is already set with this purpose.
Subject Record	CROSS_SUBJECT_RECORD_REFERENCE	The referenced entities must belong to the same subject record. Associations cannot be created between entities that exist in different subject records. The Bank Account must belong to the same Subject Record as the Business specified in the business_id parameter.