Balance Report

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

Parameter	Type	Required	Description
`currency`	string	✓	`NGN`, `GHS`, `USD`
`startdate`	string	✓	Start of date range
`enddate`	string	✓	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

Scenario	Response
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>"
}

INTRODUCTION

GETTING STARTED

ACCEPT PAYMENT

MAKE PAYMENTS

ACCOUNTS

PLUGINS AND SDKs

API BASICS

Balance Report

Overview

Fetch Balance Report

Path Parameters

Get Record

Large export sent by email

Error Responses

What next ?

​Overview

​Fetch Balance Report

​Path Parameters

​Get Record

​Large export sent by email

​Error Responses

​What next ?

Overview

Fetch Balance Report

Path Parameters

Get Record

Large export sent by email

Error Responses

What next ?