Skip to main content

​
Overview

The Balance Report API lets merchants retrieve a ledger of all wallet movements i.e payouts, settlement fees, credits, and more. Its filtered by currency and date range.
Results under 1,000 records are returned directly in the API response while results over 1,000 records are compiled into a CSV and sent to your registered email address automatically.

​
Fetch Balance Report

Retrieve a chronological ledger of wallet movements including payouts, settlement fees, credits, and debits, filtered by currency and date range.
This endpoint requires your Secret Key for authentication. Never expose your Secret Key in client-side code.

​
Path Parameters

ParameterTypeRequiredDescription
currencystring✓NGN, GHS, USD
startdatestring✓Start of date range
enddatestring✓End of date range
Both dates must follow the yyyy-MM-dd. The maximum range between startdate and enddate is 6 months.

​
Get Record

Request
curl --request GET \
  --url https://api.novacpayment.com/api/v1/balancereport/NGN/2026-06-05/2026-07-01 \
  --header 'Authorization: Bearer <your-secret-key>'
When the result set is 1,000 records or fewer, the full ledger is returned in the response body.
Response
{
  "status": true,
  "message": "Balance report details retrieved successfully",
  "data": [
    {
      "type": "payout",
      "isDebit": "yes",
      "currency": "NGN",
      "domain": "live",
      "amount": "1,186.50",
      "balanceBefore": "2,730.89",
      "balanceAfter": "1,544.39",
      "reference": "XXXXXXXXXXXXXXXXXXXXXX",
      "note": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "status": "successful",
      "date": "27/06/2026 00:30"
    },
    {
      "type": "settlement_fee",
      "isDebit": "yes",
      "currency": "NGN",
      "domain": "live",
      "amount": "18.00",
      "balanceBefore": "2,748.89",
      "balanceAfter": "2,730.89",
      "reference": "XXXXXXXXXXXXXXXXXXXXX",
      "note": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "status": "successful",
      "date": "27/06/2026 00:30"
    }
  ]
}

​
Large export sent by email

When the result set exceeds 1,000 records, the report is compiled into a CSV file and sent to your registered merchant email. The API response confirms the dispatch. 
{
  "status": true,
  "message": "Balance report sent to your email address"
}
Check the email address registered on your Novac merchant account. The CSV is typically delivered within a few minutes. If you don’t see it, check your spam folder.

​
Error Responses

ScenarioResponse
No records found for the date range"No balance record found for date range : 2026-01-01 to 2026-01-24"
Wrong date format"End Date format is wrong please use the format :: yyyy-MM-dd (eg 2025-02-09)"
Range exceeds 6 months"You can only pull a maximum of 6 months No balance report."
Start date is after end date"Start Date cannot be greater than End Date."
All error responses follow this structure: 
{
  "status": false,
  "message": "<error description>"
}

​
What next ?