Documentation

Onboarding a Business

Suggest Edits

When onboarding a business, GrailPay 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 GrailPay Bank-Link Widget to allow your customers to connect their bank accounts.

External KYB

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

Account/Routing Validation

GrailPay 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 GrailPay application. This returns an HTTP response code - 406
  • not_validated: Validation could not be completed, but the business is still added to the GrailPay application.

Endpoint

   /3p/api/v2/businesses

 

Request Payload

{
    "client_reference_id": "company_45458",
    "kyb": true,
    "first_name": "John",
    "last_name": "Dew",
    "email": "[email protected]",
    "phone": "2457856490",
    "business": {
        "name": "John Incorporation",
        "tin": "123456789",
        "transaction_fee_percent": 2.5,
        "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"
        }
    ]
}

{
    "client_reference_id": "abcd",
    "kyb": true,
    "first_name": "John",
    "last_name": "Dew",
    "email": "[email protected]",
    "phone": "2457856490",
    "business": {
        "name": "John Incorporation",
        "tin": "123456789",
        "transaction_fee_percent": 2.5,
        "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"
        }
    ],
    "bank_account": {
        "custom": {
            "account_number": "12345678901234",
            "routing_number": "056008849",
            "account_name": "Jack Jones",
            "account_type": "checking",
            "validate_account_routing": true
        }
    }
}
FieldsTypeRequiredDescription
kybbooleanNoDefault is false
client_reference_idstringNo
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.
emailstring|uniqueIf kyb = true
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 to be used for transactions associated with this business that do not supply their own transaction fee.

Range: 0 - 99.99
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_namestring if business_owners
exists		Max characters: 56
Only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces.
business_owners.*.last_namestring if business_owners
exists		Required 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.*.emailstring if business_owners
exists
business_owners.*.phonestring if business_owners
exists		without prefix +1

for eg. 2092370450
business_owners.*.dobdate:Y-m-d if business_owners
exists
business_owners.*.ssn9string if business_owners
exists		must consist of 9 digit without any special character
business_owners.*.address.line_1string if business_owners
exists
business_owners.*.address.citystring if business_owners
exists
business_owners.*.address.statestring if business_owners
exists
business_owners.*.address.zipstring if business_owners
exists		must consist of 5 digit without any special character
business_owners.*.is_beneficial_ownerboolean if business_owners
exists		If the person is a beneficial owner of the company, this should be set to true
business_owners.*.is_directorboolean if business_owners
exists		If the person is a director of the company, this should be set to true
business_owners.*.is_account_ownerboolean if business_owners
exists		If the person is an account owner of the company, this should be set to true
business_owners.*.is_share_holderboolean if business_owners
exists		If the person is a shareholder of the company, this should be set to true
business_owners.*.is_significant_control_personboolean if business_owners
exists		If 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
}

{
    "status": false,
    "message": "Invalid token.",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "unauthorized"
    }
}

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

{
    "status": false,
    "message": "Invalid token format. The token should be in the following format: ID|TOKEN_VALUE. Example: 12345|abcdefg",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "invalid_token_format"
    }
}

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

{
    "status": false,
    "message": "Invalid token format. The ID in the token must be an integer. Example: 12345|abcdefg",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "invalid_token_format"
    }
}

{
    "status": false,
    "message": "You do not have permission to access this resource from your IP address or host.",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error"
    }
}

{
    "status": false,
    "message": "The account or routing number provided is invalid",
    "data": null,
    "errors": null,
    "error_code": null
}

{
    "status": false,
    "message": "The given data was invalid.",
    "data": null,
    "errors": {
        "first_name": [
          	"The First name field is required.",
            "The first name must be a string.",
            "The first name may not be greater than 56 characters.",
            "The first name field only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "last_name": [
          	"The Last name field is required.",
            "The last name must be a string.",
            "The last name may not be greater than 56 characters.",
            "The last name field only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "email": [
          	"The Email field is required.",
            "The email must be a valid email address.",
            "The email has already been taken."
        ],
        "phone": [
          	"The Phone field is required.",
            "The phone must be a string.",
            "The phone should consist of 10 digits without the +1 prefix."
        ],
        "business.name": [
          	"The Business name field is required.",
            "The business name must be a string.",
            "The business name may not be greater than 64 characters.",
            "The business name field is required when should do kyb is true.",
            "The business name field only accepts letters (a-z, A-Z), numbers (0-9), ampersand(&), hyphens (-), periods (.), apostrophes ('), comma(,), plus (+) and spaces."
        ],
        "business.tin": [
          	"The Tin number field is required.",
            "The tin number must be a string.",
            "The tin number field is required when should do kyb is true.",
            "The tin number must consist of 9 digit."
        ],
      	"business.trading_name": [
            "The Business trading name field is required.",
          	"The Business trading name must be a string."
        ],
      	"business.entity_type": [
            "The Entity type field is required.",
          	"The Entity type must be a string."
        ],
      	"business.incorporation_date": [
            "The Incorporation date field is required.",
          	"The business owner date of birth does not match the format Y-m-d."
        ],
      	"business.incorporation_state": [
            "The Incorporation state field is required.",
          	"The Incorporation state must be valid US state."
        ],
      	"business.industry": [
          	"The Industry must be a string."
        ],
      	"business.industry_classification.code_type": [
          	"The Industry classification code type must be a string."
        ],
      	"business.industry_classification.codes": [
          	"The Industry classification codes must be an array."
        ],
      	"business.industry_classification.codes.0": [
            "The business.industry_classification.codes.0 must be a string."
        ],
      	"business.industry_classification.description": [
          	"The Industry classification description must be a string."
        ],
        "business.source_of_wealth": [
          	"The Source of wealth must be a string."
        ],
        "business.source_of_funds": [
          	"The Source of funds must be a string."
        ],
        "business.first_transaction_completed_at": [
          	"The First transaction completed date must be a date before now.",
            "The First transaction completed date does not match the format Y-m-d H:i:s."
        ],
        "business.product_type": [
          	"The Product type must be a string."
        ],
        "business.registered_as_inactive": [
          	"The Registered as inactive field must be true or false."
        ],
        "business.address_type": [
            "The Address type field is required.",
          	"The Product type must be a string."
        ],
        "business.address.line_1": [
            "The Business address line 1 field is required.",
          	"The Business address line 1 must be a string."
        ],
        "business.address.city": [
            "The Business city name field is required.",
          	"The Business city name must be a string.",
            "The Business city name may not be greater than 56 characters.",
            "The Business city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "business.address.state": [
            "The Business state name field is required.",
          	"The Business state name must be a string.",
            "The Business state name may not be greater than 2 characters.",
            "The Business state name must be valid US state."
        ],
        "business.address.zip": [
            "The Business zip code field is required.",
          	"The Business zip code must be a string.",
            "The Business zip code must consist of 5 digit."
        ],
        "business_owners": [
            "The Business owners field is required.",
          	"The business owners must be an array.",
            "The number of business owners should not exceed 5"
        ],
        "business_owners.[0-4].first_name": [
            "The business owner first name field is required.",
            "The business owner first name must be a string",
            "The business owner first name may not be greater than 56 characters.",
            "The business owner first name field only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "business_owners.[0-4].last_name": [
            "The business owner last name field is required.",
            "The business owner last name must be a string",
            "The business owner last name may not be greater than 56 characters.",
            "The business owner last name field only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "business_owners.0.email": [
            "The Business owner email field is required."
        ],
        "business_owners.0.phone": [
            "The Business owner phone field is required."
        ],
        "business_owners.[0-4].dob": [
            "The business owner date of birth field is required.",
            "The business owner date of birth does not match the format Y-m-d."
        ],
        "business_owners.[0-4].ssn9": [
            "The business owner SSN field is required.",
            "The business owner SSN must be a string",
            "The business owner SSN must consist of 9 digit"
        ],
        "business_owners.[0-4].address.line_1": [
            "The business owner address line 1 field is required.",
            "The business owner address line 1 must be a string"
        ],
        "business_owners.[0-4].address.city": [
            "The business owner city name field is required.",
            "The business owner city name must be a string",
            "The business owner city name may not be greater than 56 characters.",
            "The business owner city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "business_owners.[0-4].address.state": [
          	"The business owner state name field is required.",
            "The business owner state name must be a string.",
            "The business owner state name may not be greater than 2 characters.",
            "The business owner state name field is required.",
            "The business owner state name must be valid US state"
        ],
        "business_owners.[0-4].address.zip": [
          	"The business owner zip code field is required.",
            "The business owner zip code must be a string.",
            "The business owner zip code field is required.",
            "The business owner zip code must consist of 5 digit"
        ],
      	"business_owners.0.is_account_owner": [
            "The Business owner is account owner field is required."
        ],
        "business_owners.0.is_share_holder": [
            "The Business owner is share holder field is required."
        ],
        "business_owners.0.is_significant_control_person": [
            "The Business owner is significant control person field is required."
        ],
        "bank_account.plaid": [
            "The plaid account id and access token is required",
            "If a bank account exists, plaid should not be presented"
        ],
        "bank_account.plaid.access_token": [
            "The plaid access token must be a string.",
            "The plaid access token is required when plaid is present"
        ],
        "bank_account.plaid.account_id": [
            "The plaid account id must be a string.",
            "The plaid account id is required when plaid is present"
        ],
        "bank_account.custom": [
            "If a plaid account exists, bank account should not be presented",
            "The bank account routing number, account number, name of account and account type is required"
        ],
        "bank_account.custom.account_number": [
            "The bank account number must be a string.",
            "The bank account number is required when bank account is present",
            "The bank account number may not be greater than 17 characters."
        ],
        "bank_account.custom.routing_number": [
            "The bank routing number must be a number.",
            "The bank routing number is required when bank account is present",
            "The bank routing number must consist of 9 digit"
        ],
        "bank_account.custom.account_name": [
            "The bank account name must be a string.",
            "The bank account name is required when bank account is present"
        ],
        "bank_account.custom.account_type": [
            "The bank account type must be a string.",
            "The bank account type is required when bank account is present",
            "The bank account type should be either savings or checking"
        ]
    },
    "error_code": null
}

{
    "status": false,
    "message": "Failed to create the user.",
    "data": null,
    "errors": null,
    "error_code": null
}

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

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

Updated 3 days ago

What’s Next