Get Account Balance

Access to timely and accurate financial information is a vital resource for users of the GrailPay 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 GrailPay’s 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.

🚧

Note

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

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 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

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
}