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.
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
Fields | Type | Is Required | Description |
---|---|---|---|
should_do_kyb | boolean | By default it would befalse | |
first_name | string | ||
last_name | string | ||
string|unique | |||
phone | string | without prefix +1 | |
client_reference_id | string | ||
billing_merchant_user_uuid | string | No | The 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.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 |