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.

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

​
Billing

GrailPay’s 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.

​
Endpoint

POST /3p/api/v1/register/business

​
Request Payload

{
    "should_do_kyb": true,
    "billing_merchant_user_uuid": "93740cf6-101d-453d-802e-b7bd034a4306",
    "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"
        }
    }
}
FieldsTypeIs RequiredDescription
should_do_kybbooleanBy default it would befalse
first_namestring
last_namestring
emailstring|unique
phonestringwithout prefix +1
client_reference_idstring
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 perso
business.namestringRequired if should_do_kyb is true
business.tinstringRequired if should_do_kyb is true must consist of 9 digit without any special character
address.line_1stringRequired if should_do_kyb is true
address.line_2string
address.citystringRequired if should_do_kyb is true
address.statestring(2)Required if should_do_kyb is true
address.zipstringRequired if should_do_kyb is true must consist of 5 digit without any special character
business_ownersarray objectMax 5 owner allowed
business_owners.*.first_namestringRequired if business_owner has present
business_owners.*.last_namestringRequired if business_owner has present
business_owners.*.dobstringRequired if business_owner has present must be format of Y-m-d
business_owners.*.ssn9stringRequired if business_owner has present must consist of 9 digit without any special character
business_owners.*.address_line_1stringRequired if business_owner has present
business_owners.*.citystringRequired if business_owner has present
business_owners.*.statestringRequired if business_owner has present
business_owners.*.zipstringRequired if business_owner has present must consist of 5 digit without any special character
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

​
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
}