Onboarding a merchant is a core part of working with the GrailPay ACH API. This guide outlines the merchant onboarding workflow and provides context for common use cases. For complete request and response schemas, refer to the OpenAPI documentation.

​
What is a Merchant?

A Merchant in the GrailPay ACH API is a business entity that has completed Know Your Business (KYB) verification and is eligible to receive or process ACH payments. Merchants typically operate within a vendor’s ecosystem and are often attributed to specific billing events and revenue-sharing flows. Once onboarded, a merchant is uniquely identified by a uuid associated with the user record. This identifier is required for actions such as initiating attributing billable events and retrieving usage data.
A merchant is a specialized type of business in the GrailPay ACH API. While the onboarding process is similar to that of a business, it includes a significant number of additional fields and requirements. If you are transferring funds on behalf of a merchant entity, it must be onboarded using the merchant registration flow to meet compliance and regulatory obligations. When creating transfers, at least one side of that transfer must be associated with a KYB-verified merchant.

​
Step 1: Collect Merchant Information

To create a business we need to collect information about the point of contact and the information about the business itself, you can provide any combination of the following fields:

​
Point of Contact Information

  • First name ( point of contact for the business )
  • Last name ( point of contact for the business )
  • Email
  • Phone

​
Business Information

  • Name ( legal name of the business )
  • EIN ( Employer Identification Number )
  • Trading Name (DBA - Doing Business As)
  • Entity Type ( e.g. Sole Proprietor, LLC, etc. )
  • Incorporation Date ( date when the business was incorporated )
  • Incorporation State ( state where the business was incorporated )
  • Address ( business address )
  • Transaction Fee Percent ( default transaction fee percentage, if applicable )
  • Transaction Fee Fixed ( default transaction fee, if applicable )
  • Maximum Transaction Fee ( maximum transaction fee that can be charged on a transaction )

​
Business Owners

At least one beneficial owner is required for KYB verification. You must provide the following fields for each owner:
  • First Name
  • Last Name
  • Email
  • Phone
  • DOB ( Date of Birth )
  • SSN ( Social Security Number, last 4 or full 9 digits )
  • Address
  • Is Beneficial Owner ( must be true for at least one owner )
  • Is Director
  • Is Significant Control Person
  • Ownership Percentage

​
Required Fields for KYB Verification

  • Point of Contact Information ( all fields )
  • Business Information
    • Name
    • EIN
    • Trading Name
    • Address
    • Entity Type
  • Business Owners ( at least one beneficial owner is required for KYB)
    • All Fields
Merchants differ from businesses and individuals in that significantly more information is required to complete KYB (Know Your Business) verification. While not all fields are mandatory, we strongly recommend providing as much information as possible to ensure a smooth onboarding experience and to meet regulatory and compliance requirements.
See OpenAPI documentation for the full payload and optional parameters such as client_reference_id.

​
Testing

When testing in GrailPay’s sandbox environment, you can create a merchant as usual. To include a bank account, simply use any random 12-digit account number along with one of our supported test routing numbers. For more details, refer to the Technical Overview guide.

​
Step 2: Provide a Bank Account

You can onboard a merchant with or without a connected bank account. If you choose to provide one, we support two methods: If you’re using Plaid for bank account linking, include the following fields:
  • bank_account.plaid.access_token
  • bank_account.plaid.account_id
For integration details, refer to the OpenAPI person onboarding spec.

​
Option B: Manual Entry

You can also onboard a person using manually provided account details:
  • account_number
  • routing_number
  • account_name
  • account_type (checking or savings)
To reduce risk and ensure funds can be properly routed, enable real-time validation by including: 
"validate_account_routing": true
This will check the validity of the routing and account number during onboarding.

​
Validation Outcomes

When validate_account_routing is used, the response includes a valid_account field with one of the following values:
ValueMeaning
validAccount is valid. Merchant was successfully created.
invalidAccount is invalid. Merchant was not created. (HTTP 406)
not_validatedCould not validate. Merchant was created, but account status is unknown.

​
Step 3: Review the Response

Upon success, you’ll receive a response containing:
  • The uuid of the related to the merchant. This uuid is required for future operations such as linking bank accounts and initiating transfers.
  • Echoed values such as name and address
  • Status of the onboarding
  • KYB Status of the Merchant
  • valid_account field (if validation was enabled)
Full response schema is available in the OpenAPI docs.

​
Try It Out

You can use the API Explorer to test onboarding flows interactively. This tool allows you to enter a payload, submit a request, and view the response in real time.

​
Update KYB for a Merchant

In certain cases, you may need to update the Know Your Business (KYB) information associated with an already onboarded merchant. This could be due to changes in legal business name, address, ownership, or other regulated entity details that affect compliance status. GrailPay provides a dedicated endpoint for updating merchant KYB information. This ensures that your records remain accurate and compliant with evolving regulatory requirements. When submitting an update, the merchant will remain in an active state unless the changes require re-verification. In such cases, the KYB status may temporarily move to pending_review or on_hold until the update is processed. For complete request and response schemas, refer to the Update KYB OpenAPI Documentation.

​
Questions?

If you have questions about onboarding workflows, required fields, or errors you’re seeing in testing, please reach out to your GrailPay contact or submit a support ticket via the portal.