Skip to main content
POST
/
3p
/
api
/
v2
/
businesses
Onboard a new Business or Merchant into the ACH application ( SUNSETTING )
curl --request POST \
  --url https://api.grailpay.com/3p/api/v2/businesses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "kyb": true,
  "client_reference_id": "123456",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "1234567890",
  "business": {
    "name": "John Incorporation",
    "tin": "123456789",
    "address": {
      "line_1": "10554 W Quarles Ave",
      "city": "Littleton",
      "state": "CO",
      "zip": "80127",
      "line_2": "Suite 123"
    },
    "transaction_fee_percent": 2.5,
    "transaction_fee_fixed": 100,
    "maximum_transaction_fee": 1000,
    "payout_type": "individual",
    "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"
      ],
      "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"
  },
  "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",
        "line_2": "Suite 123"
      },
      "email": "[email protected]",
      "phone": "2457856490",
      "is_beneficial_owner": true,
      "is_director": false,
      "is_account_owner": false,
      "is_share_holder": false,
      "is_significant_control_person": false,
      "ownership_percentage": 25,
      "occupation": "Co-founder",
      "first_transaction_completed_at": "2024-05-02 16:14:25",
      "product_type": "financial"
    }
  ],
  "bank_account": {
    "custom": {
      "account_number": "123456789",
      "routing_number": "123456789",
      "account_name": "John Doe",
      "account_type": "checking"
    }
  },
  "billing_merchant_user_uuid": "2bcf2ac3-38fc-4238-a638-4f092821fc27",
  "billing_processor_mid": "21245678932"
}
'
{
  "status": true,
  "message": "<string>",
  "data": {
    "client_reference_id": "company_45458",
    "uuid": "9d264b4a-006c-4d01-acd0-730e27784c59",
    "first_name": "John",
    "last_name": "Dew",
    "email": "[email protected]",
    "phone": "2457856490",
    "business": {
      "name": "John Incorporation",
      "tin": "922454715",
      "address_type": "Registered",
      "address": {
        "street_address": "10554 W Quarles Ave",
        "additional_address": "Suite 123",
        "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": "NAICS"
      },
      "source_of_wealth": "2344",
      "source_of_funds": "Industry",
      "first_transaction_completed_at": "2024-05-02 16:14:25",
      "product_type": "financial",
      "registered_as_inactive": false,
      "transaction_fee_percent": 2.5,
      "transaction_fee_fixed": 100,
      "maximum_transaction_fee": 1000
    },
    "user_status": "APPROVED",
    "kyb_status": "APPROVED",
    "kyb_rejected_reason": null,
    "financing_credit_balance": null,
    "payout_type": "batch",
    "role": "business",
    "vendor_name": "Fintech",
    "business_owners": [
      {
        "first_name": "John",
        "last_name": "Dew",
        "dob": "2023-04-11",
        "ssn9": "123456789",
        "address_line_1": "10554 W Quarles Ave",
        "address_line_2": "Suite 123",
        "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",
        "nationality": "US",
        "occupation": "Co-founder",
        "first_transaction_completed_at": "2024-05-02 16:14:25",
        "product_type": "financial"
      }
    ],
    "valid_account": "Valid",
    "bank_account": {
      "risk": {
        "confidence_score": "0.83",
        "threshold": "0.61"
      }
    },
    "created_at": "2024-10-02 14:06:14",
    "updated_at": "2024-10-02 14:06:17"
  },
  "errors": {},
  "error_code": "<string>"
}

Authorizations

​
Authorization
string
header
required

Token-based authentication using Authorization: Bearer <YOUR_API_KEY> provided by the GrailPay Support Team.

Body

application/json
​
kyb
boolean
required
Example:

true

​
client_reference_id
string
required
Example:

"123456"

​
first_name
string
required
Example:

"John"

​
last_name
string
required
Example:

"Doe"

​
email
string
required
​
phone
string
required
Example:

"1234567890"

​
business
object
required
​
business_owners
object[]
​
bank_account
object

Bank account can be either Plaid or Custom, not both

​
billing_merchant_user_uuid
string<uuid> | null
Example:

"2bcf2ac3-38fc-4238-a638-4f092821fc27"

​
billing_processor_mid
string | null
Example:

"21245678932"

Response

Business registered successfully

Schema for a Business response

​
status
boolean

Response status

Example:

true

​
message
string

Response message

​
data
object

Business data

​
errors
object

Error details if any

​
error_code
string | null

Error code if any