​
Balance API

The Balance API allows you to check your account balance and view transaction history. This is useful for monitoring your available funds and reconciling transactions.
All Balance API endpoints require the X-Grant header for additional security. See the Authentication documentation for more details.

​
The Balance Object

{
  "available": {
    "XAF": 1000000,
    "NGN": 500000,
    "USD": 1000
  },
  "pending": {
    "XAF": 50000,
    "NGN": 0,
    "USD": 0
  }
}

​
Balance Object Properties

​
available
object
Available balance by currency that can be used for transfers
​
pending
object
Pending balance by currency that is not yet available for use

​
API Endpoints

Check Balance

GET /balance
Retrieve your current account balance across all currencies.
This endpoint requires the X-Grant header in addition to your API key.

​
Example Request

curl https://api.notchpay.co/balance \
  -H "Authorization: YOUR_PUBLIC_KEY" \
  -H "X-Grant: YOUR_PRIVATE_KEY"

Check Balance for a Specific Currency

GET /balance/{currency}
Retrieve your current account balance for a specific currency.

​
Path Parameters

​
currency
string
required
Three-letter ISO currency code (e.g., XAF, NGN, USD)

List Balance History

GET /balance/history
Retrieve a list of balance changes with pagination.

​
Query Parameters

​
limit
integer
Number of items per page (default: 30, max: 100)
​
page
integer
Page number (default: 1)
​
currency
string
Filter by currency code
​
type
string
Filter by transaction type: payment, transfer, refund, adjustment
​
date_start
string
Start date filter (format: YYYY-MM-DD)
​
date_end
string
End date filter (format: YYYY-MM-DD)

Get Transaction Details

GET /balance/history/{id}
Retrieve details of a specific balance transaction.

​
Path Parameters

​
id
string
required
ID of the transaction to retrieve

​
Transaction Types

payment

Incoming payment from a customer

transfer

Outgoing transfer to a beneficiary

refund

Refund of a payment

adjustment

Manual adjustment to your balance

​
Best Practices

Regular Reconciliation

Regularly check your balance history and reconcile it with your internal records to ensure accuracy.Use the transaction references to match transactions with your system.

Monitor Available Balance

Before initiating transfers, check your available balance to ensure you have sufficient funds.Remember that pending funds are not available for transfers.

Secure Your Private Key

Keep your private key (X-Grant) secure as it provides access to sensitive balance information and transfer capabilities.Never share your private key in client-side code or public repositories.

Use Webhooks for Updates

Set up webhooks to receive real-time notifications about balance changes instead of polling the balance API.This provides more timely updates and reduces API calls.

Payments API

Accept payments to increase your balance

Transfers API

Send money to beneficiaries

Webhooks API

Receive notifications about balance changes