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

object

Available balance by currency that can be used for transfers

object

Pending balance by currency that is not yet available for use

API Endpoints

Check Balance

Request
Response

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"

fetch('https://api.notchpay.co/balance', {
  method: 'GET',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notchpay.co/balance",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: YOUR_PUBLIC_KEY",
    "X-Grant: YOUR_PRIVATE_KEY"
  ]
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

{
  "code": 200,
  "status": "OK",
  "message": "Balance retrieved",
  "balance": {
    "available": {
      "XAF": 1000000,
      "NGN": 500000,
      "USD": 1000
    },
    "pending": {
      "XAF": 50000,
      "NGN": 0,
      "USD": 0
    }
  }
}

Check Balance for a Specific Currency

Request
Response

GET /balance/{currency}

Retrieve your current account balance for a specific currency.

Path Parameters

string

required

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

{
  "code": 200,
  "status": "OK",
  "message": "Balance retrieved",
  "balance": {
    "currency": "XAF",
    "available": 1000000,
    "pending": 50000
  }
}

List Balance History

Request
Response

GET /balance/history

Retrieve a list of balance changes with pagination.

Query Parameters

integer

Number of items per page (default: 30, max: 100)

integer

Page number (default: 1)

string

Filter by currency code

string

Filter by transaction type: payment, transfer, refund, adjustment

string

Start date filter (format: YYYY-MM-DD)

string

End date filter (format: YYYY-MM-DD)

{
  "code": 200,
  "status": "OK",
  "message": "Balance history retrieved",
  "totals": 50,
  "last_page": 2,
  "current_page": 1,
  "selected": 30,
  "items": [
    {
      "id": "txn_123456789",
      "type": "payment",
      "amount": 5000,
      "currency": "XAF",
      "reference": "pay_123456789",
      "description": "Payment from customer@example.com",
      "created_at": "2023-01-01T12:00:00Z"
    },
    {
      "id": "txn_987654321",
      "type": "transfer",
      "amount": -2000,
      "currency": "XAF",
      "reference": "trf_987654321",
      "description": "Transfer to John Doe",
      "created_at": "2023-01-01T14:00:00Z"
    },
    // More transactions...
  ]
}

Get Transaction Details

Request
Response

GET /balance/history/{id}

Retrieve details of a specific balance transaction.

Path Parameters

string

required

ID of the transaction to retrieve

{
  "code": 200,
  "status": "OK",
  "message": "Transaction retrieved",
  "transaction": {
    "id": "txn_123456789",
    "type": "payment",
    "amount": 5000,
    "currency": "XAF",
    "reference": "pay_123456789",
    "description": "Payment from customer@example.com",
    "metadata": {
      "customer_id": "cus_123456789",
      "payment_method": "mobile_money"
    },
    "created_at": "2023-01-01T12:00:00Z"
  }
}

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

Introduction

Core Resources

Additional Resources

API Specification

Balance API

Balance API

The Balance Object

Balance Object Properties

API Endpoints

Check Balance

Example Request

Check Balance for a Specific Currency

Path Parameters

List Balance History

Query Parameters

Get Transaction Details

Path Parameters

Transaction Types

payment

transfer

refund

adjustment

Best Practices

Regular Reconciliation

Monitor Available Balance

Secure Your Private Key

Use Webhooks for Updates

Payments API

Transfers API

Webhooks API

​Balance API

​The Balance Object

​Balance Object Properties

​API Endpoints

Check Balance

​Example Request

Check Balance for a Specific Currency

​Path Parameters

List Balance History

​Query Parameters

Get Transaction Details

​Path Parameters

​Transaction Types

payment

transfer

refund

adjustment

​Best Practices

Regular Reconciliation

Monitor Available Balance

Secure Your Private Key

Use Webhooks for Updates

​Related Resources

Payments API

Transfers API

Webhooks API

Balance API

The Balance Object

Balance Object Properties

API Endpoints

Example Request

Path Parameters

Query Parameters

Path Parameters

Transaction Types

Best Practices

Related Resources