Overview
In the GrailPay ACH API, a user can take the form of a Person, Business, or Merchant. These entities work together to represent the full lifecycle of participants in your ACH flow — from individuals initiating transactions, to businesses receiving funds, to merchants operating within a platform. This guide provides a centralized reference for managing users across all three entity types. It includes endpoints for:- Updating, listing, and retrieving people
- Updating, listing, and retrieving businesses
- Updating, listing, and retrieving merchants
- Deleting a person
People
In the GrailPay ACH API, a Person represents an individual user within your platform. A person may be directly involved in sending or receiving funds, or they may be linked to a Business or Merchant entity as part of an onboarding or transaction workflow. This flexible structure allows you to model a wide range of real-world scenarios—from independent users to employees or representatives acting on behalf of a larger organization. Person records support essential attributes such as name, contact information, and optional associations to other entities, enabling rich identity and relationship management across your integration.A Person can be associated with a Business or Merchant. When retrieving a single Person or
listing all People, there is a relations object in the response that will contain the UUID of the Business or Merchant
associated with that Person.
List People
To retrieve a list of people, you can use the endpoint that returns all people associated with your vendor. This endpoint allows you to fetch a paginated list of people, including their UUIDs, names, and email addresses. For complete request and response schemas, refer to the List Users OpenAPI Documentation.Fetch a Person
To retrieve a specific person, you will need the UUID of the person you want to retrieve. This endpoint allows you to fetch detailed information about a person, including their name, email, phone number, and the vendor they are associated with. For complete request and response schemas, refer to the Fetch a User OpenAPI Documentation.Update a Person
To update a person, you must supply the UUID of the person record you wish to modify along with the fields you intend to change. This endpoint allows you to update basic identifying information such as name, email, or phone number. Only fields explicitly passed in the request will be updated — all other fields will remain unchanged. This ensures you can make partial updates without affecting the full record. For complete request and response schemas, refer to the Update Person OpenAPI Documentation.Delete a Person
To delete a specific person, you will need the UUID of the person you want to delete. This endpoint allows you to remove a person from the system, which will also make any associated information such as bank accounts, transfers, and related businesses or merchants inaccessible. For complete request and response schemas, refer to the Delete User OpenAPI Documentation.Businesses
In the GrailPay ACH API, a Business is a simple entity type that represents an organization capable of sending or receiving funds. Unlike Merchants, Businesses do not undergo KYB (Know Your Business) verification. However, they are modeled separately from People to ensure proper ACH classification and compliance with NACHA regulations.A Business is automatically associated with a Person when it is onboarded. When retrieving a single Business or
listing all Businesses, there is a relations object in the response that will contain the UUID of the Person associated
with that Business.
List Businesses
To retrieve a list of all businesses associated with your API token, use the list endpoint. This will return a paginated array of business records including attributes such as UUID, legal name, and timestamps. For full request and response definitions, refer to the List Businesses OpenAPI Documentation.Fetch a Business
To fetch details for a specific business, provide the business UUID. The response will include core attributes and metadata related to the business entity. For full request and response definitions, refer to the Fetch a Business OpenAPI Documentation.Update a Business
To update an existing business, send a PATCH request with the updated fields—such as name, address, or contact information. This helps maintain accurate records for downstream ACH processing and reporting.While transactions are typically created using the UUID of the Person associated with a Business, this endpoint
specifically requires the UUID of the Business entity itself.
Merchants
In the GrailPay ACH API, a Merchant is a specialized type of Business that has completed KYB (Know Your Business) verification. KYB is a regulatory requirement that ensures the identity and legitimacy of a business entity before it can participate in financial transactions. At least one party in every transaction must be KYB-verified, which is why Merchants play a critical role in GrailPay’s compliance and payment workflows. Although Merchants are technically a kind of Business, they require additional data during onboarding and are subject to stricter validation rules. This distinction allows GrailPay to maintain compliance while enabling robust and flexible transaction models.A Person is automatically associated with a Merchant when it is onboarded. When retrieving a single Merchant or
listing all Merchants, there is a relations object in the response that will contain the UUID of the Person associated
with that Merchant.
List Merchants
To retrieve a list of all merchants associated with your API token, use the list endpoint. The response will return a paginated array of merchant records, including their UUIDs, legal names, and KYB status. For full request and response definitions, refer to the List Merchants OpenAPI Documentation.Fetch a Merchant
To fetch details for a specific merchant, provide the merchant UUID. The response will include all core attributes, as well as KYB-related fields and associated metadata. For full request and response definitions, refer to the Fetch A Merchant OpenAPI Documentation.Update a Merchant
To update an existing merchant, send a PATCH request to the update endpoint with any updated fields—such as legal name, contact information, or address. For more information about KYB verification and requirements, refer to the KYB 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"
If a merchant’s KYB status needs to be corrected or additional data is required to pass KYB checks, this endpoint
should be used to resubmit or correct their business information.
While transactions are typically created using the UUID of the Person associated with a Merchant, this endpoint
specifically requires the UUID of the Merchant entity itself.