Access to timely and accurate financial information is a vital resource for users of the ACH API. One of our key features is the ability to retrieve the current balance of any bank account linked to a user. To utilize this feature, the account must first be registered through Bank Link Widget. You will then need to provide the following information as path parameters when making the API call:
  • uuid: The UUID of the user.
  • account_uuid: The UUID of the bank account associated with that user.
  • batch_merchant_user_uuid: This optional query parameter can be passed to associated the billable event of making a Balance Check with a specific merchant.
Keep in mind that this balance check is only available to accounts connected through our Bank Link Widget. If attempted on an account added through the API ( manual_account ), we will respond with an error with a status code of 403.

​
Billing

Our ACH 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 as a query parameter:
  • 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

GET   /3p/api/v2/users/{uuid}/bank-accounts/{account_uuid}

​
Response Object

{
    "status": true,
    "message": "",
    "data": {
        "available_balance": "25425"
    },
    "errors": null,
    "error_code": null
}

​
Errors & Warnings

{
    "status": false,
    "message": "Only a bank account connected through GrailPay's bank link widget can provide access to the account balance",
    "data": null,
    "errors": null,
    "error_code": null
}
HTTP Status CodeError CodeReasonMessage
400client_errorMissing Accept HeaderInvalid value provided for Accept header.
400client_errorMissing Path ParametersYour request could not be processed due to invalid or missing parameters.
401client_errorInvalid Token FormatInvalid token format. The token should be in the following format: ID|TOKEN_VALUE. Example: 12345|abcdefg
401client_errorInvalid Token FormatInvalid token format. The ID in the token must be an integer. Example: 12345|abcdefg
401client_errorUnauthorizedInvalid token.
403client_errorInvalid Account TypeOnly a bank account connected through our bank link widget can provide access to the account balance.
403client_errorUser Scheduled for DeletionThis user is not available as they have been scheduled for deletion.
404client_errorUser Not FoundThe User was not found.
404client_errorBank Account Not FoundNo bank account found with the given details.
406Invalid Billing User UUIDThe requested billing merchant user uuid does not exist.
406Billing Merchant DeletedThe billing merchant is deleted and cannot be used for billing purposes.
503system_errorUnable to fetch the balanceWe are unable to fetch the account balance.