Onboard a Business

** This endpoint is scheduled for deprecation. Please refer to the V2 Business Onboarding API

The first step in using GrailPay is onboarding new or existing businesses to create user accounts. GrailPay will then return a UUID, which serves as the unique identifier for each business, to be used for further requests. Please note that only one business can be created per request.

The registration information typically includes details such as the user's phone, address, bank account etc. The API does not require the user's address, and business detail unless should_do_kyb is set to true.

While bank account details are optional in the registration API, 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.

GrailPay offers a service to connect customer bank accounts with the GrailPay Bank Link Widget. Please refer to your client agreement if this service is included in your service package.

📘
Know Your Business (KYB) Data
It is recommended to send all available KYB data for at least one side of each transaction.
The following KYB data is required:
Exact business entity name
Business tax ID number (EIN)
Business Address

Endpoint

/3p/api/v1/register/business

Request Payload

{
    "should_do_kyb": true,
    "business": {
        "name": "Jack Inc.",
        "tin": "961862955"
    },
    "address": {
        "line_1": "20 Elmora Ave",
        "city": "Elizabeth",
        "state": "NJ",
        "zip": "07202"
    },
    "bank_account": {
        "custom": {
            "account_number": "12345678901234",
            "routing_number": "056008849",
            "account_name": "Jack Jones",
          	"account_type": "checking"
        }
    }
}

{
    "should_do_kyb": true,
    "business": {
        "name": "Jack Inc.",
        "tin": "961862955"
    },
    "address": {
        "line_1": "20 Elmora Ave",
        "city": "Elizabeth",
        "state": "NJ",
        "zip": "07202"
    },
    "business_owners": [
        {
            "first_name": "Mark",
            "last_name": "Ville",
            "dob": "1925-05-01",
            "ssn9": "800771213",
            "address_line_1": "605 Atwood Dr",
            "city": "Downingtown",
            "state": "PA",
            "zip": "07002"
        }
    ],
    "bank_account": {
        "custom": {
            "account_number": "12345678901234",
            "routing_number": "056008849",
            "account_name": "Jack Jones",
          	"account_type": "checking"
        }
    }
}

Fields	Type	Description
should_do_kyb	boolean	By default it would be`false`
first_name	string
last_name	string
email	string\|unique
phone	string	without prefix +1
client_reference_id	string
business.name	string	Required if `should_do_kyb` is `true`
business.tin	string	Required if `should_do_kyb` is `true` must consist of 9 digit without any special character
address.line_1	string	Required if `should_do_kyb` is `true`
address.line_2	string
address.city	string	Required if `should_do_kyb` is `true`
address.state	string(2)	Required if `should_do_kyb` is `true`
address.zip	string	Required if `should_do_kyb` is `true` must consist of 5 digit without any special character

business_owners	array object	Max 5 owner allowed
*business_owners..first_name**	string	Required if `business_owner` has present
*business_owners..last_name**	string	Required if `business_owner` has present
*business_owners..dob**	string	Required if `business_owner` has present must be format of Y-m-d
*business_owners..ssn9**	string	Required if `business_owner` has present must consist of 9 digit without any special character
*business_owners..address_line_1**	string	Required if `business_owner` has present
*business_owners..city**	string	Required if `business_owner` has present
*business_owners..state**	string	Required if `business_owner` has present
*business_owners..zip**	string	Required if `business_owner` has present must consist of 5 digit without any special character

bank_account.plaid.access_token	string	Plaid user access token
bank_account.plaid.account_id	string	Plaid user account id
bank_account.custom.account_number	string	Bank account number maximum of 17 characters
bank_account.custom.routing_number	string	Bank account routing number 9-digit ABA routing transit number associated with the account without any special character
bank_account.custom.account_name	string	Name of account in bank
bank_account.custom.account_type	string	Bank account type Possible values: savings checking

Response Object

{
    "status": true,
    "message": "",
    "data": {
        "client_reference_id": "",
        "uuid": "401c79dd-d38c-4c3a-8edf-1afac5914d2d",
        "first_name": null,
        "last_name": null,
        "name": "Jack Inc.",
        "tin": "961862955",
        "user_status": "Approved|On Hold|Rejected",
        "kyb_status": "Approved|In Review|Failed|null",
        "email": null,
        "phone": null,
        "financing_credit_balance": null,
        "address": {
            "street_address": "20 Elmora Ave",
            "additional_address": "",
            "city": "Elizabeth",
            "state": "NJ",
            "country": "US",
            "zip": "07202"
        },
        "business_owners": [
            {
                "first_name": "Olive",
                "last_name": "Vein",
                "dob": "1996-05-04",
                "ssn9": "123456789",
                "address_line_1": "778 E Encore Dr",
                "city": "Hanford",
                "state": "CA",
                "zip": "93230"
            }
        ],
        "created_at": "2023-06-10 14:15:54",
        "updated_at": "2023-06-10 14:15:54"
    },
    "errors": []
}

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 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 given data was invalid.",
    "data": null,
    "errors": {
        "first_name": [
            "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 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 must be a valid email address.",
            "The email has already been taken"
        ],
        "phone": [
            "The phone must be a string.",
            "The phone should consist of 10 digits without the +1 prefix"
        ],
        "business.name": [
            "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 must be a string.",
            "The tin number field is required when should do kyb is true.",
            "The tin number must consist of 9 digit"
        ],
        "address.line_1": [
            "The address line 1 must be a string.",
            "The address line 1 field is required when should do kyb is true."
        ],
        "address.city": [
            "The city name must be a string.",
            "The city name may not be greater than 56 characters.",
            "The city name field is required when should do kyb is true.",
            "The city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "address.state": [
            "The state must be a string.",
            "The state may not be greater than 2 characters.",
            "The state field is required when should do kyb is true.",
            "The state must be valid US state"
        ],
        "address.zip": [
            "The zip code must be a string.",
            "The zip code field is required when should do kyb is true.",
            "The zip code must consist of 5 digit"
        ],
        "business_owners": [
            "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-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].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].state": [
            "The business owner state must be a string.",
            "The business owner state may not be greater than 2 characters.",
            "The business owner state field is required.",
            "The business owner state must be valid US state"
        ],
        "business_owners.[0-4].zip": [
            "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"
        ],
        "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
}

📘Know Your Business (KYB) Data

Endpoint

Request Payload

Response Object

Errors & Warnings

📘
Know Your Business (KYB) Data