A bank account plays an important role in GrailPay’s transaction processing between the payer and payee. When using the registration API, you have the option to include the user’s bank account information along with their personal information. If, for some reason, the bank information was not provided during the registration API process, you can still request to add the bank account information for the person or business using this API. Additionally, if the existing bank account information for the person or business is not accessible in GrailPay, you can add new bank account information through this API. This API includes a path parameter <user_uuid>, which refers to the unique identifier of the registered business or individual that was obtained from the registration API.

​
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/bank-account/{user_uuid}  

​
Request Payload

{
  "billing_merchant_user_uuid": "93740cf6-101d-453d-802e-b7bd034a4306",
	"custom": {
		"account_number": "12345678901234",
		"routing_number": "056008849",
		"account_name": "Jack Jones",
		"account_type": "checking"
	}
}
FieldsTypeIs RequiredDescription
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
plaid.access_tokenstringPlaid user access token
plaid.account_idstringPlaid user account id
custom.account_numberstringBank account number maximum of 17 characters
custom.routing_numberstringBank account routing number 9-digit ABA routing transit number associated with the account
custom.account_namestringName of account in bank
custom.account_typestringBank account type Possible values: savings checking

​
Response Object

{
    "status": true,
    "message": "Bank account has been added.",
    "data": {
        "uuid": "9bb541c4-05bc-48f8-8bcd-fd0fe5c903d7",
        "account_number": "12345678901234",
        "routing_number": "056008849",
        "account_name": "Jack Jones",
        "account_type": "checking",
        "aggregator_type": "manual",
        "created_at": "2024-04-02 03:19:07",
        "is_default": true
    },
    "errors": []
}

​
Errors & Warnings

CodeReasonMessage
401
403
406Invalid Billing Merchant User UUIDThe requested billing merchant user uuid does not exist.
406Billing Merchant has been deletedThe billing merchant is deleted and cannot be used for billing purposes.
422