Get Account Balance

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
}

{
    "status": false,
    "message": "This user is not available as they have been scheduled for deletion",
    "data": null,
    "errors": null,
    "error_code": null
}

{
    "status": false,
    "message": "The User was not found",
    "data": null,
    "errors": null,
    "error_code": null
}

{
    "status": false,
    "message": "No bank account found with the given details",
    "data": null,
    "errors": null,
    "error_code": null
}

// When the UUID passed for billing does not exist
{
    "status": false,
    "message": "The requested billing merchant user uuid does not exist.",
    "data": null,
    "errors": null,
    "error_code": null
}

// When the UUID passed for billing belongs to a user that has been deleted
{
    "status": false,
    "message": "The billing merchant is deleted and cannot be used for billing purposes.",
    "data": null,
    "errors": null,
    "error_code": null
}

{
    "status": false,
    "message": "We are unable to fetch the account balance",
    "data": null,
    "errors": null,
    "error_code": null
}

HTTP Status Code	Error Code	Reason	Message
400	`client_error`	Missing Accept Header	Invalid value provided for Accept header.
400	`client_error`	Missing Path Parameters	Your request could not be processed due to invalid or missing parameters.
401	`client_error`	Invalid Token Format	Invalid token format. The token should be in the following format: ID\|TOKEN_VALUE. Example: 12345\|abcdefg
401	`client_error`	Invalid Token Format	Invalid token format. The ID in the token must be an integer. Example: 12345\|abcdefg
401	`client_error`	Unauthorized	Invalid token.
403	`client_error`	Invalid Account Type	Only a bank account connected through our bank link widget can provide access to the account balance.
403	`client_error`	User Scheduled for Deletion	This user is not available as they have been scheduled for deletion.
404	`client_error`	User Not Found	The User was not found.
404	`client_error`	Bank Account Not Found	No bank account found with the given details.
406		Invalid Billing User UUID	The requested billing merchant user uuid does not exist.
406		Billing Merchant Deleted	The billing merchant is deleted and cannot be used for billing purposes.
503	`system_error`	Unable to fetch the balance	We are unable to fetch the account balance.

Getting Started

Users

Transactions

Payouts

Refunds

Bank Accounts

Webhooks

Billing

Get Account Balance

Billing

Endpoint

Response Object

Errors & Warnings

​Billing

​Endpoint

​Response Object

​Errors & Warnings

Billing

Endpoint

Response Object

Errors & Warnings