Onboarding a Business
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.
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.
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
POST /3p/api/v2/businesses
Request Payload
| Fields | Type | Required | Description |
|---|---|---|---|
| kyb | boolean | No | Default is false |
| client_reference_id | string | No | |
| 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 person |
| first_name | string | If kyb = true | Max characters: 56 Only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes (’), and spaces. |
| last_name | string | If kyb = true | Max characters: 56 Only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes (’), and spaces. |
| string|unique | If kyb = true | ||
| phone | string | If kyb = true | without prefix +1 for eg. 2092370450 |
| business.name | string | If kyb = true | Legal 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.tin | string | If kyb = true | must consist of 9 digit without any special character |
| business.transaction_fee_percent | float | A 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_name | string | If kyb = true | Trading name of the business |
| business.entity_type | string | Business entity type. For eg. Sole Trader, Limited Company etc. | |
| business.incorporation_date | date:Y-m-d | Date when the company was incorporated | |
| business.incorporation_state | string(2) | State where the company was incorporated (US only) | |
| business.industry | string | Nature of business | |
| business.industry_classification.code_type | string | if industry_classification exists | Type of industry classification code. eg. SIC etc. Required |
| business.industry_classification.codes | array string | if industry_classification exists | Industry classification codes |
| business.industry_classification.description | string | if industry_classification exists | Description of the industry classification code |
| business.source_of_wealth | string | Source of wealth of the company | |
| business.source_of_funds | string | Source of initial deposit of the company | |
| business.first_transaction_completed_at | datetime:Y-m-d H:i:s | Original timestamp of when the person completed their first transaction | |
| business.product_type | string | ||
| business.registered_as_inactive | boolean | ||
| business.address_type | string | If kyb = true | Type of address. For eg. Registered, Trading, Legal etc. |
| business.address.line_1 | string | If kyb = true | |
| business.address.city | string | If kyb = true | |
| business.address.state | string(2) | If kyb = true | |
| business.address.zip | string | If kyb = true | must consist of 5 digit without any special character |
| business_owners | array object | If kyb = true | Max 5 owner allowed |
| business_owners.*.first_name | string | 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_name | string | 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.*.email | string | if business_owners exists | |
| business_owners.*.phone | string | if business_owners exists | without prefix +1 for eg. 2092370450 |
| business_owners.*.dob | date:Y-m-d | if business_owners exists | |
| business_owners.*.ssn9 | string | if business_owners exists | must consist of 9 digit without any special character |
| business_owners.*.address.line_1 | string | if business_owners exists | |
| business_owners.*.address.city | string | if business_owners exists | |
| business_owners.*.address.state | string | if business_owners exists | |
| business_owners.*.address.zip | string | if business_owners exists | must consist of 5 digit without any special character |
| business_owners.*.is_beneficial_owner | boolean | if business_owners exists | If the person is a beneficial owner of the company, this should be set to true |
| business_owners.*.is_director | boolean | if business_owners exists | If the person is a director of the company, this should be set to true |
| business_owners.*.is_account_owner | boolean | if business_owners exists | If the person is an account owner of the company, this should be set to true |
| business_owners.*.is_share_holder | boolean | if business_owners exists | If the person is a shareholder of the company, this should be set to true |
| business_owners.*.is_significant_control_person | boolean | if business_owners exists | If the person is a has significant control of the company, this should be set to true |
| business_owners.*.ownership_percentage | number | If 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.*.occupation | string | Primary occupation of the person | |
| business_owners.*.first_transaction_completed_at | datetime:Y-m-d H:i:s | Original timestamp of when the person completed their first transaction | |
| business_owners.*.product_type | string | ||
| 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 | |
| bank_account.custom.validate_account_routing | boolean | No | Perform validation on the account and routing number. If validation fails, the business will not be created. |