Balance & Transactions | RizPay Developer API

Monitor your account balance and review transaction history through the API.

Check Balance

Get your current account balance:

bash

curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  https://my.rizpay.app/api/partners/v1/account/balance

Response:

json

{
  "status": { "code": 200, "message": "Balance retrieved" },
  "data": {
    "balance": "50000.00",
    "currency": "NGN",
    "updated_at": "2026-05-18T10:30:00+01:00"
  }
}

Field	Description
`balance`	Current available balance
`currency`	Currency code (NGN)
`updated_at`	Last balance update time

Required Scope: read_balance

List Transactions

Get your transaction history with optional filters:

bash

curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  "https://my.rizpay.app/api/partners/v1/account/transactions?status=successful&per_page=50"

Response:

json

{
  "status": { "code": 200, "message": "Transactions retrieved" },
  "data": [
    {
      "id": "txn_abc123",
      "type": "transaction",
      "attributes": {
        "amount": "500.0",
        "currency": "NGN",
        "status": "successful",
        "category": "purchase",
        "description": "Purchase of MTN Airtime",
        "reference": "a1b2c3d4e5f607181736",
        "external_reference": "1736234400A1B2C3",
        "product_type": "airtime",
        "phone_number": "08012345678",
        "meter_number": null,
        "price": {
          "product_amount": "500.00",
          "fee_amount": "0.00",
          "total_debit": "500.00",
          "currency": "NGN",
          "basis": "face_value"
        },
        "created_at": "2026-05-18T10:30:00+01:00",
        "updated_at": "2026-05-18T10:30:02+01:00"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_pages": 10,
    "total_count": 487
  }
}

Each transaction uses the same nested data[].attributes shape as a purchase. Funding, commission, and transfer rows omit product_type, phone_number, meter_number, and (for non-purchases) the price block. There is no separate completion timestamp: use updated_at.

Required Scope: read_transactions

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (max: 100, default: 20)
`status`	string	Filter by status: `pending`, `successful`, `failed`, `reversed`
`category`	string	Filter by category: `funding`, `purchase`, `withdrawal`, `transfer`, `commission`, `promo`
`from`	ISO8601	Start date (e.g., `2024-01-15T00:00:00Z`)
`to`	ISO8601	End date (e.g., `2024-01-31T23:59:59Z`). Must be after `from`
`reference`	string	Filter by external_reference

Filter by Status

bash

# Successful transactions only
GET /account/transactions?status=successful

GET /account/transactions?status=pending

GET /account/transactions?status=failed

Filter by Category

bash

# Purchase transactions only
GET /account/transactions?category=purchase

# Funding transactions only
GET /account/transactions?category=funding

# Withdrawal transactions only
GET /account/transactions?category=withdrawal

Filter by Date Range

bash

# Transactions from January 2024
GET /account/transactions?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z

Find by Reference

bash

# Find transaction by your reference
GET /account/transactions?reference=1736234400A1B2C3

Validation Errors

Invalid filter parameters return a 400 Bad Request with details:

json

{
  "status": { "code": 400, "message": "Bad Request" },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid status 'invalid'. Valid values: pending, successful, failed, reversed"
  }
}

Common validation errors:

Error	Cause
Invalid status	Status not in: `pending`, `successful`, `failed`, `reversed`
Invalid category	Category not in: `funding`, `purchase`, `withdrawal`, `transfer`, `commission`, `promo`
Invalid 'from' date format	Date not in ISO8601 format
Invalid 'to' date format	Date not in ISO8601 format
'from' date must be before 'to' date	`from` is after `to`

Get Transaction Details

Get details for a specific transaction by ID or external_reference:

bash

# By transaction ID
curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  https://my.rizpay.app/api/partners/v1/account/transactions/txn_abc123

# By external_reference (16 chars: 10 digits + 6 alphanumeric)
curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  https://my.rizpay.app/api/partners/v1/account/transactions/1736234400A1B2C3

Response:

json

{
  "status": { "code": 200, "message": "Transaction details retrieved" },
  "data": {
    "id": "txn_abc123",
    "type": "transaction",
    "attributes": {
      "amount": "500.0",
      "currency": "NGN",
      "status": "successful",
      "category": "purchase",
      "description": "Purchase of MTN Airtime",
      "reference": "a1b2c3d4e5f607181736",
      "external_reference": "1736234400A1B2C3",
      "product_type": "airtime",
      "phone_number": "08012345678",
      "meter_number": null,
      "price": {
        "product_amount": "500.00",
        "fee_amount": "0.00",
        "total_debit": "500.00",
        "currency": "NGN",
        "basis": "face_value"
      },
      "created_at": "2026-05-18T10:30:00+01:00",
      "updated_at": "2026-05-18T10:30:02+01:00"
    }
  }
}

Transaction Statuses

Status	Description
`pending`	Processing with provider
`successful`	Completed successfully
`failed`	Failed (balance refunded)
`reversed`	Reversed/refunded after success

Requery Transaction

For pending transactions, you can trigger a status requery from the provider:

bash

curl -X POST \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  https://my.rizpay.app/api/partners/v1/purchases/txn_abc123/query

Response:

json

{
  "status": { "code": 200, "message": "Query initiated" },
  "data": {
    "id": "txn_abc123",
    "status": "pending",
    "message": "Transaction status will be updated shortly"
  }
}

Note: Requery is only available for pending transactions. The actual status update happens asynchronously - use webhooks to get notified.

Low Balance Alerts

Configure low balance alerts in your account settings:

Go to Settings > API
Enable "Low Balance Alerts"
Set your threshold amount

When your balance drops below the threshold:

You'll receive an email notification
A account.low_balance webhook is triggered (if subscribed)

Complete Example

javascript

async function getAccountSummary(apiKey) {
  const BASE_URL = "https://my.rizpay.app/api/partners/v1";
  const headers = { Authorization: `Bearer ${apiKey}` };

  // Get balance
  const balanceRes = await fetch(`${BASE_URL}/account/balance`, { headers });
  const balance = await balanceRes.json();

  // Get recent transactions
  const txnRes = await fetch(`${BASE_URL}/account/transactions?per_page=10`, {
    headers,
  });
  const transactions = await txnRes.json();

  // Get today's stats
  const today = new Date().toISOString().split("T")[0];
  const statsRes = await fetch(
    `${BASE_URL}/account/transactions?from=${today}T00:00:00Z&status=successful`,
    { headers }
  );
  const todayTxns = await statsRes.json();

  return {
    currentBalance: balance.data.balance,
    recentTransactions: transactions.data,
    todayCount: todayTxns.pagination.total_count,
    todayVolume: todayTxns.data.reduce(
      (sum, txn) => sum + parseFloat(txn.amount),
      0
    ),
  };
}

Next Steps

Pagination - Navigate large result sets
Webhooks - Get real-time transaction updates