Documentation

Get Account Balance

GrailPay's Bank Link widget provides the ability to retrieve the latest balance from a bank account, which helps us validate the transaction amount.

With this request, you can also obtain the approval status of a transaction amount (e.g., is the transaction amount above or below the current balance) before processing it through ACH. You only need to provide the user_uuid and the transaction amount.

🚧

Note

For a manual bank account, we will be unable to retrieve the balance from the bank account. In such a scenario, we will respond with an error, indicating a status code of 403.


Endpoint

   /3p/api/v1/bank-account/balance/{user_uuid}

 

Request Payload

Note: Here are the query parameters that will be appended to the URL

for eg. /3p/api/v1/bank-account/balance/aae3664b-db18-428c-9a2f-a876f259a7c3/?amount=1000

FieldsTypeIs RequiredDescription
amountintAmount in cents only

Response Object

{
    "status": true,
    "message": "",
    "data": {
        "available_balance": "25425"
    },
    "errors": null,
    "error_code": null
}
{
    "status": true,
    "message": "",
    "data": {
        "approval": "true|false"
    },
    "errors": null,
    "error_code": null
}
{
    "status": false,
    "message": "The linked account has expired",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "expired_linked_account"
    }
}
{
    "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": {
        "type": "client_error",
        "subtype": null
    }
}
{
    "status": false,
    "message": "The User was not found",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "client_error",
        "subtype": "uuid_not_found"
    }
}
{
    "status": false,
    "message": "Something went wrong, please try again later",
    "data": null,
    "errors": null,
    "error_code": {
        "type": "system_error",
        "subtype": "unhandled_error"
    }
}

Errors & Warnings

HTTP Status CodeError CodeSub Error CodeMessage
400client_errormissing_accept_headerInvalid value provided for Accept header.
400client_errormissing_path_parameterYour 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_errorOnly a bank account connected through GrailPay's bank link widget can provide access to the account balance
403client_errorexpired_linked_accountThe linked account has expired
404client_erroruuid_not_foundThe User was not found
4221. The amount must be at least 10. 2. The amount must be an integer.
500system_errorunhandled_errorSomething went wrong, please try again later