--- title: Balance & Transactions description: Check your account balance and transaction history --- 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: 1. Go to [Settings > API](https://my.rizpay.app/settings/api) 2. Enable "Low Balance Alerts" 3. 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](/docs/core-concepts/pagination) - Navigate large result sets - [Webhooks](/docs/webhooks/overview) - Get real-time transaction updates