When onboarding a business, we will return a UUID which serves as the unique identifier to be used for further API requests. Please note that only one business can be created per request. While the bank account details are optional parameters when registering a business, they are required for processing transactions for your customers. If a user did not provide their bank account information during registration, you can still add it later using the Add Bank Account API or you can use the Bank-Link SDK to allow your customers to connect their bank accounts.

​
External KYB

If your processor’s KYB underwriting has been approved by us and configured for conducting KYB independently then we will not perform our own KYB check. Setting the kyb flag to true in this instance will enable additional field requirements to satisfy bank compliance.

​
Billing

The ACH API supports associating specific billable events with a particular merchant, enabling precise attribution for billing purposes. This feature allows you to link the UUID of a user tied to a merchant (a business that has undergone KYB verification) to the billing event recorded for the API call. To attribute the billing event to a merchant, include the following parameter in your request payload:
  • billing_merchant_user_uuid: The unique identifier (UUID) of the user associated with the merchant to whom this billable event should be attributed.
By leveraging this parameter, you can ensure accurate and detailed tracking of billable events across your integrations.

​
Account/Routing Validation

Our ACH API supports account and routing number validation to prevent failed transactions and fund reversals. This validation is performed by setting the validate_account_routing flag to true when onboarding a business with a custom bank account

​
Validation Results:

  • valid: The account and routing number are valid, and the business is added successfully.
  • invalid: The account or routing number is invalid, and the business is not added to the application. This returns an HTTP response code - 406
  • not_validated: Validation could not be completed, but the business is still added to the application.

​
Endpoint

POST /3p/api/v2/businesses

​
Request Payload

{
    "client_reference_id": "company_45458",
    "billing_merchant_user_uuid": "f1085408-111f-40f1-b31a-d970cf0d4994",
    "kyb": true,
    "first_name": "John",
    "last_name": "Dew",
    "email": "[email protected]",
    "phone": "2457856490",
    "business": {
        "name": "John Incorporation",
        "tin": "123456789",
        "transaction_fee_percent": 2.5,
        "max_transaction_fee": 1000,
        "payout_type": "batch",
        "trading_name": "John Incorporation",
        "entity_type": "Sole Trader",
        "incorporation_date": "2024-02-02",
        "incorporation_state": "CO",
        "industry": "Nature of business",
        "industry_classification": {
            "code_type": "SIC",
            "codes": [
                "NAICS 42",
                "NAICS 45"
            ],
            "description": "abcdefg"
        },
        "source_of_wealth": "2344",
        "source_of_funds": "skjdkd",
        "first_transaction_completed_at": "2024-05-02 16:14:25",
        "product_type": "financial",
        "registered_as_inactive": false,
        "address_type": "Registered",
        "address": {
            "line_1": "10554 W Quarles Ave",
            "city": "Littleton",
            "state": "CO",
            "zip": "80127"
        }
    },
    "business_owners":[
        {
            "first_name": "John",
            "last_name": "Dew",
            "dob": "2023-04-11",
            "ssn9": "123456789",
            "address": {
                "line_1": "10554 W Quarles Ave",
                "city": "Littleton",
                "state": "CO",
                "zip": "80127"
            },
            "is_beneficial_owner": true,
            "is_director": false,
            "is_account_owner": false,
            "is_share_holder": false,
            "is_significant_control_person": false,
            "ownership_percentage": 25,
            "email": "[email protected]",
            "phone": "2457856490",
            "occupation": "Co-founder",
            "first_transaction_completed_at": "2024-05-02 16:14:25",
            "product_type": "financial"
        }
    ]
}
FieldsTypeRequiredDescription
kybbooleanNoDefault is false
client_reference_idstringNo
billing_merchant_user_uuidstringNoThe UUID of the user associated with the merchant that should be associated with the billable event that is created when onboarding a new person
first_namestringIf kyb = trueMax characters: 56 Only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes (’), and spaces.
last_namestringIf kyb = trueMax characters: 56 Only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes (’), and spaces.
emailstringIf kyb = trueEmail is validated based on construction and domain validity
phonestringIf kyb = truewithout prefix +1 for eg. 2092370450
business.namestringIf kyb = trueLegal name of the business Max characters: 64 Only accepts letters (a-z, A-Z), numbers (0-9), ampersand(&), hyphens (-), periods (.), apostrophes (’), comma(,), plus (+) and spaces.
business.tinstringIf kyb = truemust consist of 9 digit without any special character
business.transaction_fee_percentfloatA default transaction fee percentage to be used for transactions associated with this business that do not supply their own transaction fee. Range: 0 - 99.99
business.transaction_fee_fixedfloatA default transaction fee that is fixed to be used for transactions associated with this business that do not supply their own transaction fee.
business.maximum_transaction_feeintegerThe maximum transaction fee that can be charged on a transaction. This is sent in cents. eg. $10.00 = 1000
business.payout_typestringA string value representing the type of payout the entity should recieve. Possible Values: batch, individual ( default: individual )
business.trading_namestringIf kyb = trueTrading name of the business
business.entity_typestringBusiness entity type. For eg. Sole Trader, Limited Company etc.
business.incorporation_datedate:Y-m-dDate when the company was incorporated
business.incorporation_statestring(2)State where the company was incorporated (US only)
business.industrystringNature of business
business.industry_classification.code_typestringif industry_classification existsType of industry classification code. eg. SIC etc. Required
business.industry_classification.codesarray stringif industry_classification existsIndustry classification codes
business.industry_classification.descriptionstringif industry_classification existsDescription of the industry classification code
business.source_of_wealthstringSource of wealth of the company
business.source_of_fundsstringSource of initial deposit of the company
business.first_transaction_completed_atdatetime:Y-m-d H:i:sOriginal timestamp of when the person completed their first transaction
business.product_typestring
business.registered_as_inactiveboolean
business.address_typestringIf kyb = trueType of address. For eg. Registered, Trading, Legal etc.
business.address.line_1stringIf kyb = true
business.address.citystringIf kyb = true
business.address.statestring(2)If kyb = true
business.address.zipstringIf kyb = truemust consist of 5 digit without any special character
business_ownersarray objectIf kyb = trueMax 5 owner allowed
business_owners.*.first_namestringif business_owners existsMax characters: 56 Only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes (’), and spaces.
business_owners.*.last_namestringif business_owners existsRequired if business_owners has present Max characters: 56 Only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes (’), and spaces.
business_owners.*.emailstringif business_owners exists
business_owners.*.phonestringif business_owners existswithout prefix +1 for eg. 2092370450
business_owners.*.dobdate:Y-m-dif business_owners exists
business_owners.*.ssn9stringif business_owners existsmust consist of 9 digit without any special character
business_owners.*.address.line_1stringif business_owners exists
business_owners.*.address.citystringif business_owners exists
business_owners.*.address.statestringif business_owners exists
business_owners.*.address.zipstringif business_owners existsmust consist of 5 digit without any special character
business_owners.*.is_beneficial_ownerbooleanif business_owners existsIf the person is a beneficial owner of the company, this should be set to true
business_owners.*.is_directorbooleanif business_owners existsIf the person is a director of the company, this should be set to true
business_owners.*.is_account_ownerbooleanif business_owners existsIf the person is an account owner of the company, this should be set to true
business_owners.*.is_share_holderbooleanif business_owners existsIf the person is a shareholder of the company, this should be set to true
business_owners.*.is_significant_control_personbooleanif business_owners existsIf the person is a has significant control of the company, this should be set to true
business_owners.*.ownership_percentagenumberIf the person is a shareholder of the company, this should be set to their ownership percentage, as a value between 0 and 100
business_owners.*.occupationstringPrimary occupation of the person
business_owners.*.first_transaction_completed_atdatetime:Y-m-d H:i:sOriginal timestamp of when the person completed their first transaction
business_owners.*.product_typestring
bank_account.plaid.access_tokenstringPlaid user access token
bank_account.plaid.account_idstringPlaid user account id
bank_account.custom.account_numberstringBank account number maximum of 17 characters
bank_account.custom.routing_numberstringBank account routing number 9-digit ABA routing transit number associated with the account without any special character
bank_account.custom.account_namestringName of account in bank
bank_account.custom.account_typestringBank account type Possible values: savings checking
bank_account.custom.validate_account_routingbooleanNoPerform validation on the account and routing number. If validation fails, the business will not be created.

​
Response Object

{
    "status": true,
    "message": "",
    "data": {
        "client_reference_id": "company_45458",
        "uuid": "866db83c-3e5e-48d4-8221-d29eaf6471e5",
        "first_name": "John",
        "last_name": "Dew",
        "email": "[email protected]",
        "phone": "2457856490",
        "business": {
            "name": "John Incorporation",
            "tin": "123456789",
            "transaction_fee_percent": 2.5,
            "address_type": "2344",
            "address": {
                "street_address": "10554 W Quarles Ave",
                "city": "Littleton",
                "state": "CO",
                "country": "US",
                "zip": "80127"
            },
            "trading_name": "John Incorporation",
            "entity_type": "Sole Trader",
            "incorporation_date": "2024-02-02",
            "incorporation_state": "CO",
            "industry": "Nature of business",
            "industry_classification": {
                "code_type": "SIC",
                "codes": [
                    "NAICS 42",
                    "NAICS 45"
                ],
                "description": "abcdefg"
            },
            "source_of_wealth": "2344",
            "source_of_funds": "skjdkd",
            "first_transaction_completed_at": "2024-06-24 16:14:25",
            "product_type": "financial",
            "registered_as_inactive": true
        },
        "user_status": "APPROVED",
        "kyb_status": "IN_REVIEW",
        "financing_credit_balance": null,
        "business_owners": [
            {
                "first_name": "John",
                "last_name": "Dew",
                "dob": "2024-07-11",
                "ssn9": "123456782",
                "address_line_1": "10554 W Quarles Ave",
                "city": "Littleton",
                "state": "CO",
                "zip": "80127",
                "email": "[email protected]",
                "phone": "2457856490"
            }
        ],
        "valid_account": "valid",
        "created_at": "2024-06-25 13:57:03",
        "updated_at": "2024-06-25 13:57:09"
    },
    "errors": null,
    "error_code": null
}

​
Errors & Warnings

{
    "status": false,
    "message": "Invalid value provided for Accept header.",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "missing_accept_header"
    }
}

-----------------------------------------------------

{
    "status": false,
    "message": "Plaid account ID couldn't be verified",
    "data": null,
    "errors": null,
    "error_code": null
}

-----------------------------------------------------

{
    "status": false,
    "message": "Invalid plaid account ID or access token",
    "data": null,
    "errors": null,
    "error_code": null
}

-----------------------------------------------------

{
    "status": false,
    "message": "Invalid routing_number: 000000001. This routing number has an invalid check digit.",
    "data": null,
    "errors": null,
    "error_code": null
}