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.

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.

Example Request

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

GET /balance

Retrieve your current account balance across all currencies.

Example Request

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

{
  "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

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)

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)

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

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 /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)

{
  "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

GET /balance/history/{id}

Retrieve details of a specific balance transaction.

Path Parameters

string

required

ID of the transaction to retrieve

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

Example Request

Check Balance for a Specific Currency

Path Parameters

Path Parameters

List Balance History

Query Parameters

Query Parameters

Get Transaction Details

Path Parameters

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

Introduction

Core Resources

Additional Resources

API Specification

​Balance API

​The Balance Object

​Balance Object Properties

​API Endpoints

Check Balance

​Example Request

​Example Request

Check Balance for a Specific Currency

​Path Parameters

​Path Parameters

List Balance History

​Query Parameters

​Query Parameters

Get Transaction Details

​Path Parameters

​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

Example Request

Path Parameters

Path Parameters

Query Parameters

Query Parameters

Path Parameters

Path Parameters

Transaction Types

Best Practices

Related Resources