Balance

This endpoint allows the merchant to check their API account balance in real-time (or multiple sub-accounts if the platform supports it).

It is often used before executing a payout or to verify the available settlement capacity.

GET /v1/balance

Authentication

Purpose

• Check the current balance of the merchant account.
• Ensure that the available balance allows executing a payment or transfer.
• Track financial movements of the account (e.g., for display in a dashboard).
• Identify attached sub-accounts (e.g., by currency or activity).

Request Example

curl -X GET https://api.novasend.app/v1/balance \
  -H "Authorization: Basic base64(api_key:api_client)" \
  -H "Content-Type: application/json"

Response Example

[
  {
    "balance": 4676,
    "availableBalance": 4676,
    "reference": "merchant_gh8jpoipkrxhjsm0",
    "currency": "XOF"
  }
]

Field Interpretation

💡 In some cases, a merchant may have multiple balances depending on currencies or environments (Prod / Sandbox).

Difference Between balance and availableBalance

Example:

• balance = 10,000

• availableBalance = 7,000

  → This means 3,000 XOF are still pending settlement (e.g., an unconfirmed payment).

  Typical Use Cases

  | Use Case | Description |

  | --- | --- | | Before a payout | Verify that availableBalance ≥ amount + fees before issuing the transfer. | | Merchant dashboard | Display real-time balance in a portal or mobile app. | | Reconciliation | Compare balances received via API with those in the local database. | | Error prevention | Prevent a payment if the balance is insufficient. |

Multiple Responses

The API may return multiple objects in the array if the merchant has multi-currency accounts or segmented sub-accounts (by region, product, or service).

Example:

[
  {
    "balance": 4676,
    "availableBalance": 4676,
    "reference": "merchant_gh8jpoipkrxhjsm0",
    "currency": "XOF"
  },
  {
    "balance": 1230,
    "availableBalance": 980,
    "reference": "merchant_usd_ahjs87s2",
    "currency": "USD"
  }
]

Possible Errors

Security and obligation

• Never expose the api_key on the frontend side.
• Always use a production key distinct from the sandbox one.
• Cache the balance if you display the information frequently (e.g., dashboard).
• Set up an internal alert if availableBalance drops below a certain threshold.