Balance Inquiry

With this utility, merchants can check the balance(s) for the different currencies they might hold. The section describes the various wallet types and balances that are returned.

Wallet Types

Wallet Type	Description
MERCHANT_COLLECTION	This wallet holds funds accumulated from funds collection of a specific currency. Funds directly deposited into the merchant account for a gievn currency would also live in a wallet of this type.
MERCHANT_PAYOUT	All the funds the merchant accout wishes to designate for disbursements will be stored in a special wallet of this type. The merchant will be allowed to provision funds here by transferrig from the collection account to this one.
SERVICE_PAYMENTS	All the funds the merchant accout wishes to designate for service payments (e.g. PRN payments) will be stored in a special wallet of this type. The merchant will be allowed to provision funds here by transferrig from the collection account to this one.

Balance Descriptions

Balance Name	Description
available_balance	The amount/balance available for use. This the amount the merchant account has access to for any other platform operations
actual_balance	This is the total balance of a given currency for a certain merchant account wallet. It's the summation of all the balances in the given wallet.
uncleared_balance	This is the amount yet to be made available to the merchant account for use.
reserve_balance	In the event transactions are done using payment options for which a rolling reserve is implemented (e.g. card options), the accumulated rolling reserve amounts would be deposited under this balance

The endpoint returns currency wallets belonging to the merchant account

GET https://gwapisdbx.govbill.ug/data/wallet-balances

The endpoint retrieves the balance(s) by currency

Query Parameters

Name	Type	Description
currency	String	The currency whose balances should be retrieved (Optional)

Headers

Name	Type	Description
public-key*	String	The Public Key as shared in the approval email
secret-key*	String	The Secret Key as shared in the approval email

200: OK Returns array of wallet balances based on the currency

{
    "code": 200,
    "status": "success",
    "message": "Request completed successfully.",
    "data": {
        "merchant_wallets": [
            {
                "available_balance": 40000,
                "actual_balance": 40000,
                "currency": "UGX",
                "uncleared_balance": 40000,
                "reserve_balance": 0,
                "wallet_type": "MERCHANT_COLLECTION"
            },
            {
                "available_balance": 0,
                "actual_balance": 0,
                "currency": "UGX",
                "uncleared_balance": 0,
                "reserve_balance": 0,
                "wallet_type": "MERCHANT_PAYOUT"
            }
        ]
    }
}

401: Unauthorized When one of the keys is invalid

{
  "code": 401,
  "status": "error",
  "message": "Unauthorized API access. Invalid Merchant Secret Key",
  "data": {}
}

422: Unprocessable Entity Balances request could not be processed

{
    "code": 422,
    "status": "error",
    "message": "Request Failed. Merchant Account: HEARTY GIFTS is not configured to transact in: USD",
    "data": {}
}