Skip to main content
The first step in using GrailPay is onboarding new or existing persons to create user accounts. GrailPay will then return a UUID, which serves as the unique identifier for each person, to be used for further requests. Please note that only one person can be created per request. The registration information typically includes details such as the user’s email, phone, address etc. GrailPay offers a service to connect customer bank accounts with the GrailPay Bank Link Widget. Please refer to your client agreement if this service is included in your service package.

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

​
Endpoint

POST /3p/api/v1/register/person

​
Request Payload

{
    "first_name": "Jack",
    "last_name": "Jones",
    "billing_merchant_user_uuid": "ea1ff884-9dfe-437c-a9e7-9aa6c8e02e0a",
    "address": {
        "line_1": "20 Elmora Ave",
        "line_2": "",
        "city": "Elizabeth",
        "state": "NJ",
        "zip": "07202"
    }
}
FieldsTypeIs RequiredDescription
first_namestring
last_namestring
emailstring|unique
phonestringwithout prefix +1
client_reference_idstring
billing_merchant_user_uuidstringNoThe UUID of the user associated with the merchant that should be associated with the billable event that is created when onboarding a new perso
address.line_1string
address.line_2string
address.citystring
address.statestring(2)
address.zipstringmust consist of 5 digit without any special character
bank_account.plaid.access_tokenstringPlaid user access token
bank_account.plaid.account_idstringPlaid user account id
bank_account.custom.account_numberstringBank account number maximum of 17 characters
bank_account.custom.routing_numberstringBank account routing number 9-digit ABA routing transit number associated with the account without any special character
bank_account.custom.account_namestringName of account in bank
bank_account.custom.account_typestringBank account type Possible values: savings checking

​
Response Object

{
    "status": true,
    "message": "",
    "data": {
        "client_reference_id": "",
        "uuid": "401c79dd-d38c-4c3a-8edf-1afac5914d2d",
        "status": "Approved|On Hold|Rejected",
        "first_name": "Jack",
        "last_name": "Jones",
        "email": null,
        "phone": null,
        "address": {
            "street_address": "20 Elmora Ave",
            "additional_address": "",
            "city": "Elizabeth",
            "state": "NJ",
            "country": "US",
            "zip": "07202"
        },
        "created_at": "2023-06-10 14:15:54",
        "updated_at": "2023-06-10 14:15:54",
        "role": "person"
    },
    "errors": []
}

​
Errors & Warnings

{
    "status": false,
    "message": "Invalid value provided for Accept header.",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "missing_accept_header"
    }
}

-----------------------------------------------------

{
    "status": false,
    "message": "Plaid account ID couldn't be verified",
    "data": null,
    "errors": null,
    "error_code": null
}

-----------------------------------------------------

{
    "status": false,
    "message": "Invalid routing_number: 000000001. This routing number has an invalid check digit.",
    "data": null,
    "errors": null,
    "error_code": null
}