Overview

This API lets the platform fetch the current balance of a virtual account created on Decentro's stack.

Flow

Below is the flow for using this API.

The platform creates a virtual account using the Create a Virtual Account v3 API.
The payer transfers funds to the virtual account from their bank account.
The platform gets a Account Balance Callback/Webhook from Decentro
The platform can also fetch the balance of a virtual account using this API

Managing family of virtual accounts

Clients can easily manage fetching balance of their virtual accounts by selecting from either a single virtual account, a family of virtual accounts, or all virtual accounts associated with a consumer.

To effectively identify the relevant virtual accounts, clients can use one of the following identifiers::

Identifier	Results
account_number	The API will respond with the balance of the specific virtual_account_number in question.
custom_va_number	The API will respond with the cumulative balance of all virtual account numbers across various banks linked to the specified custom VA number.
customer_va_identifier	The API will respond with the cumulative balance of all virtual account numbers across different banks associated with the given customer VA identifier.
consumer_urn	The API will respond with the cumulative balance of all virtual accounts across banks created for the consumer.

API Endpoints

Below are the API endpoints to be used by the platform basis the environments.

Environment	Endpoint
Staging / Sandbox	https://staging.api.decentro.tech/v3/banking/balance
Production	https://api.decentro.tech/v3/banking/balance

Response keys

Below is the response keys

Response key	Description
error_account_disabled	Your account has been disabled. Please reach out to support
error_malformed_request	Malformed request detected.
error_empty_request	Request body is empty. Kindly check the payload and retry.
error_invalid_method	The method is not allowed for the requested URL.
error_unsanitized_values	Unsanitized values detected for key(s): <KEY NAME(s)>. Kindly sanitize the corresponding values by removing unicode, non-ascii, and special characters such as . @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) ( and retry.
error_invalid_client_id	Authentication failed. Please use a valid Client ID.
error_empty_client_id	Client ID cannot be empty. Hint: client_id (string)
error_invalid_format_client_id	Client ID is not of type string. Hint: client_id (string)
error_invalid_client_secret	Authentication failed. Please use a valid Client Secret.
error_empty_client_secret	Client Secret cannot be empty. Hint: client_secret (string)
error_invalid_format_client_secret	Client Secret is not of type string. Hint: client_secret (string)
error_invalid_bearer_token	Authentication failed. Please use a valid bearer token.
error_empty_bearer_token	Bearer Token cannot be empty. Hint: bearer_token (string)
error_invalid_format_bearer_token	Bearer Token is not of type string. Hint: bearer_token (string)
error_invalid_consumer_urn	Consumer URN passed is not valid.
error_empty_consumer_urn	Consumer URN cannot be empty. Hint: consumer_urn (string)
error_invalid_format_consumer_urn	Consumer URN is not of type string. Hint: consumer_urn (string)
error_format_account_number	Account Number is not of type string. Hint: account_number (string)
error_length_account_number	account_number length must be between [minimum] and [maximum] characters.
error_format_fetch_compliance_balance	Fetch Compliance Balance is not of type boolean. Hint: fetch_compliance_balance (boolean, true or false)
error_empty_consumer_urn	fetch_compliance_balance is required if consumer_urn is provided.
error_missing_provider_code	provider_code is required if the account is a Virtual Account (VA).
error_invalid_format_provider_code	Provider Code is not of type string. Hint: provider_code (string)
error_length_provider_code	provider_code length must be 4 characters.
error_format_fetch_child_balance	Fetch Child Balance is not of type boolean. Hint: fetch_child_balance (boolean, true or false)
error_empty_consumer_urn	fetch_child_balance is required if consumer_urn is provided.