Onboard a Person

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.

​

Account/Routing Validation

GrailPay supports account and routing number validation to prevent failed transactions and fund reversals. This validation is performed by setting the validate_account_routing flag to true when onboarding a person with a custom bank account

​

Validation Results:

• valid: The account and routing number are valid, and the person is added successfully.
• invalid: The account or routing number is invalid, and the person is not added to the GrailPay application. This returns an HTTP response code - 406
• not_validated: Validation could not be completed, but the person is still added to the GrailPay application.

​

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": "93740cf6-101d-453d-802e-b7bd034a4306",
    "address": {
        "line_1": "20 Elmora Ave",
        "line_2": "",
        "city": "Elizabeth",
        "state": "NJ",
        "zip": "07202"
    }
}

​

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",
        "valid_account": "valid"
    },
    "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
}