Skip to main content
Onboarding a merchant is a core part of working with the GrailPay Payments 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 Payments API is a business entity that has met GrailPay’s compliance requirements 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 Payments 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 compliance-verified merchant.

​
Compliance Requirements

A Merchant is not fully onboarded until all compliance checks have been completed. Before a Merchant can process transactions, they must pass both KYB (Know Your Business) verification for the business entity and KYC (Know Your Customer) verification for each Beneficial Owner. Until these checks are complete, the Merchant’s Compliance Status will remain Pending, and they will be unable to transact. These verification processes run asynchronously after the initial onboarding request is submitted. To monitor a Merchant’s ability to transact, you should subscribe to the ComplianceStatusChanged webhook event, which will notify your system whenever a Merchant’s Compliance Status changes. For a detailed explanation of compliance requirements, verification outcomes, and corrective actions, refer to the Compliance Status Overview guide.
When testing in the Sandbox environment, Social Security Numbers (SSNs) must follow specific formatting rules to be considered valid. The SSN:
  • Cannot begin with "000" or any value in the range "900–999"
  • Cannot have "00" as the middle two digits
  • Cannot end in "0000"
Any other valid 9-digit SSN format outside of these constraints is acceptable for testing purposes.

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

​
Beneficial Owners

At least one beneficial owner is required for compliance 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 Compliance 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 Compliance Approval )
  • All Fields except Ownership Percentage for each Beneficial Owner
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 Documentation.

​
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 fraud risk and ensure funds can be successfully routed, we recommend enabling real-time bank account validation during onboarding. This feature is powered by our Account Intelligence product, which provides intelligent validation of routing and account numbers at the time of submission. To enable this, include an actions object in your onboarding request: 
{
    "actions": {
        "account_intelligence": {
            "version": "v3",
            "name_match": true
        }
    }
}
This validation step confirms that the provided routing and account numbers are both valid and correctly formatted. If name_match is enabled, it also checks that the account holder’s name aligns with the expected identity. In addition to these checks, the response includes a Risk Score and a set of decisioning insights that explain how the account was evaluated. To understand the full structure of the response and how to interpret the results, refer to our Account Intelligence documentation. Although optional, enabling this validation is strongly recommended for all production integrations to reduce failure rates and improve payout reliability.

​
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 accountsand initiating transfers.
  • Echoed values such as name and address
  • Status of the onboarding
  • Compliance Status of the Merchant
  • An account intelligence object (if validation was requested)
Full response schema is available in the OpenAPI Documentation.

​
Step 4: Monitor Compliance Status

After onboarding, the Merchant’s Compliance Status determines whether they can process transactions. Compliance Status is computed in real-time based on the results of KYB (Know Your Business) verification for the business entity and KYC (Know Your Customer) verification for each Beneficial Owner. A Merchant’s Compliance Status will be one of the following:
StatusDescriptionCan Transact?
PendingKYB and/or KYC verification is still in progress.❌ No
ApprovedThe business has passed KYB and all Beneficial Owners have passed KYC.✅ Yes
In ReviewKYB requires additional manual review; all Beneficial Owners have passed KYC.❌ No
RejectedThe business failed KYB or one or more Beneficial Owners failed KYC.❌ No
A Merchant is Rejected if either the business fails KYB or any Beneficial Owner fails KYC. Only one failure is required for rejection.
You can monitor Compliance Status by retrieving the merchant record or by listening for the ComplianceStatusChanged webhook event. For a detailed explanation of compliance requirements, verification processes, and corrective actions, refer to the Compliance Status Overview guide.

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

​
Questions?

If you’re encountering any issues, please reach out to [email protected].