Documentation

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.


Endpoint

   /3p/api/v1/register/person

 

Request Payload

{
    "first_name": "Jack",
    "last_name": "Jones",
    "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
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
}
{
    "status": false,
    "message": "Invalid token.",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "unauthorized"
    }
}

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

{
    "status": false,
    "message": "Invalid token format. The token should be in the following format: ID|TOKEN_VALUE. Example: 12345|abcdefg",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "invalid_token_format"
    }
}

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

{
    "status": false,
    "message": "Invalid token format. The ID in the token must be an integer. Example: 12345|abcdefg",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "invalid_token_format"
    }
}
{
    "status": false,
    "message": "You do not have permission to access this resource from your IP address or host.",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error"
    }
}
{
    "status": false,
    "message": "The given data was invalid.",
    "data": null,
    "errors": {
        "first_name": [
            "The first name must be a string.",
            "The first name may not be greater than 56 characters.",
            "The first name field only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "last_name": [
            "The last name must be a string.",
            "The last name may not be greater than 56 characters.",
            "The last name field only accepts letters (a-z, A-Z, À-ÿ), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "email": [
            "The email must be a valid email address.",
            "The email has already been taken"
        ],
        "phone": [
            "The phone must be a string.",
            "The phone should consist of 10 digits without the +1 prefix"
        ],
        "address.line_1": [
            "The address line 1 must be a string."
        ],
        "address.city": [
            "The city name must be a string.",
            "The city name may not be greater than 56 characters.",
            "The city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces."
        ],
        "address.state": [
            "The state must be a string.",
            "The state may not be greater than 2 characters.",
            "The state must be valid US state"
        ],
        "address.zip": [
            "The zip code must be a string.",
            "The zip code must consist of 5 digit"
        ],
        "bank_account.plaid": [
            "The plaid account id and access token is required",
            "If a bank account exists, plaid should not be presented"
        ],
        "bank_account.plaid.access_token": [
            "The plaid access token must be a string.",
            "The plaid access token is required when plaid is present"
        ],
        "bank_account.plaid.account_id": [
            "The plaid account id must be a string.",
            "The plaid account id is required when plaid is present"
        ],
        "bank_account.custom": [
            "If a plaid account exists, bank account should not be presented",
            "The bank account routing number, account number, name of account and account type is required"
        ],
        "bank_account.custom.account_number": [
            "The bank account number must be a string.",
            "The bank account number is required when bank account is present",
            "The bank account number may not be greater than 17 characters."
        ],
        "bank_account.custom.routing_number": [
            "The bank routing number must be a number.",
            "The bank routing number is required when bank account is present",
            "The bank routing number must consist of 9 digit"
        ],
        "bank_account.custom.account_name": [
            "The bank account name must be a string.",
            "The bank account name is required when bank account is present"
        ],
        "bank_account.custom.account_type": [
            "The bank account type must be a string.",
            "The bank account type should be either savings or checking"
        ]
    },
    "error_code": null
}