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

Fields	Type	Is Required	Description
amount	int		Amount 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 Code	Error Code	Sub Error Code	Message
400	`client_error`	`missing_accept_header`	Invalid value provided for Accept header.
400	`client_error`	`missing_path_parameter`	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`		Only a bank account connected through GrailPay's bank link widget can provide access to the account balance
403	`client_error`	`expired_linked_account`	The linked account has expired
404	`client_error`	`uuid_not_found`	The User was not found
422			1. The amount must be at least 10. 2. The amount must be an integer.
500	`system_error`	`unhandled_error`	Something went wrong, please try again later

🚧Note

Endpoint

Request Payload

Response Object

Errors & Warnings

🚧
Note