Get Account Balance

Overview

Get your current account balance in Algerian Dinar (DZD). The balance represents available funds that can be used for top-ups, orders, and other services.

When your balance reaches a low threshold, a notification will be sent to your registered email address.

Response

success

boolean

required

true for successful requests

data

object

required

Show properties

balance

number

Current account balance in DZD

Example Request

curl --request GET \
  --url https://api.oneclickdz.com/v3/account/balance \
  --header 'X-Access-Token: YOUR_API_KEY'

Example Response

{
  "success": true,
  "data": {
    "balance": 1326.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.710Z"
  }
}

Use Cases

Pre-Transaction Check

Verify sufficient funds before processing orders

Balance Display

Show current balance in your application UI

Low Balance Alerts

Monitor balance and alert when running low

Financial Reports

Track balance changes over time

Integration Examples

Pre-Transaction Validation

async function canProcessTransaction(amount) {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/account/balance",
    {
      headers: { "X-Access-Token": API_KEY },
    }
  );

  const data = await response.json();

  if (!data.success) {
    throw new Error("Failed to check balance");
  }

  const balance = data.data.balance;

  if (balance < amount) {
    throw new Error(
      `Insufficient balance. Required: ${amount} DZD, Available: ${balance} DZD`
    );
  }

  return true;
}

// Usage
try {
  await canProcessTransaction(500);
  // Proceed with transaction
} catch (error) {
  console.error(error.message);
  // Show error to user
}

Balance Monitoring

class BalanceMonitor {
  constructor(apiKey, lowBalanceThreshold = 1000) {
    this.apiKey = apiKey;
    this.lowBalanceThreshold = lowBalanceThreshold;
    this.lastBalance = null;
  }

  async checkBalance() {
    const response = await fetch(
      "https://api.oneclickdz.com/v3/account/balance",
      {
        headers: { "X-Access-Token": this.apiKey },
      }
    );

    const data = await response.json();

    if (!data.success) {
      console.error("Failed to check balance:", data.error);
      return;
    }

    const currentBalance = data.data.balance;

    // Check for low balance
    if (currentBalance < this.lowBalanceThreshold) {
      this.onLowBalance(currentBalance);
    }

    // Check for significant changes
    if (this.lastBalance !== null) {
      const change = currentBalance - this.lastBalance;

      if (Math.abs(change) > 100) {
        this.onBalanceChange(change, currentBalance);
      }
    }

    this.lastBalance = currentBalance;
    return currentBalance;
  }

  onLowBalance(balance) {
    console.warn(`⚠️ Low balance alert: ${balance} DZD`);
    // Send notification to admin
    this.sendNotification({
      type: "low_balance",
      balance: balance,
      threshold: this.lowBalanceThreshold,
    });
  }

  onBalanceChange(change, newBalance) {
    const changeType = change > 0 ? "increased" : "decreased";
    console.log(
      `Balance ${changeType} by ${Math.abs(
        change
      )} DZD. New balance: ${newBalance} DZD`
    );
  }

  sendNotification(data) {
    // Implement your notification logic
    console.log("Notification:", data);
  }

  startMonitoring(intervalMinutes = 5) {
    // Initial check
    this.checkBalance();

    // Periodic checks
    setInterval(() => {
      this.checkBalance();
    }, intervalMinutes * 60 * 1000);
  }
}

// Usage
const monitor = new BalanceMonitor(API_KEY, 1000);
monitor.startMonitoring(5); // Check every 5 minutes

Balance Caching

class BalanceCache {
  constructor(apiKey, cacheSeconds = 30) {
    this.apiKey = apiKey;
    this.cacheSeconds = cacheSeconds;
    this.cache = {
      balance: null,
      timestamp: 0,
    };
  }

  async getBalance(forceRefresh = false) {
    const now = Date.now();
    const cacheAge = (now - this.cache.timestamp) / 1000;

    // Return cached value if valid
    if (
      !forceRefresh &&
      this.cache.balance !== null &&
      cacheAge < this.cacheSeconds
    ) {
      return this.cache.balance;
    }

    // Fetch fresh balance
    const response = await fetch(
      "https://api.oneclickdz.com/v3/account/balance",
      {
        headers: { "X-Access-Token": this.apiKey },
      }
    );

    const data = await response.json();

    if (!data.success) {
      throw new Error(`Failed to fetch balance: ${data.error.message}`);
    }

    // Update cache
    this.cache = {
      balance: data.data.balance,
      timestamp: now,
    };

    return this.cache.balance;
  }

  invalidateCache() {
    this.cache.timestamp = 0;
  }
}

// Usage
const balanceCache = new BalanceCache(API_KEY, 30);

// First call - fetches from API
const balance1 = await balanceCache.getBalance();

// Second call within 30 seconds - returns cached value
const balance2 = await balanceCache.getBalance();

// Force refresh
const balance3 = await balanceCache.getBalance(true);

Best Practices

Check Before Transactions

Always verify sufficient balance before initiating transactions

// ✅ Good
const balance = await getBalance();
if (balance >= requiredAmount) {
  await sendTopUp(...);
}

// ❌ Bad
await sendTopUp(...); // Might fail with NO_BALANCE error

Cache Wisely

Cache balance for 30-60 seconds to reduce API calls

javascript // Cache       balance but invalidate after transactions const balance = await       balanceCache.getBalance(); await sendTopUp(...);       balanceCache.invalidateCache(); // Refresh after transaction

Handle Errors Gracefully

Implement proper error handling

async function getSafeBalance() {
  try {
    const response = await fetch('https://api.oneclickdz.com/v3/account/balance', {
      headers: { 'X-Access-Token': API_KEY }
    });
    
    const data = await response.json();
    
    if (!data.success) {
      console.error('Balance check failed:', data.error);
      return null;
    }
    
    return data.data.balance;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}

Monitor Low Balance

Set up alerts for low balance

const LOW_BALANCE_THRESHOLD = 1000;

async function checkAndAlert() {
  const balance = await getBalance();
  
  if (balance < LOW_BALANCE_THRESHOLD) {
    await sendAlert({
      type: 'low_balance',
      balance: balance,
      message: `Balance is low: ${balance} DZD`
    });
  }
}

Error Responses

401 - Unauthorized

{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid"
  },
  "requestId": "req_abc123"
}

500 - Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Developer was notified and will check shortly"
  },
  "requestId": "req_abc123"
}

List Transactions

View transaction history

Send Mobile Top-Up

Send a mobile top-up

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

OCPay

Overview

Response

Example Request

Example Response

Use Cases

Pre-Transaction Check

Balance Display

Low Balance Alerts

Financial Reports

Integration Examples

Pre-Transaction Validation

Balance Monitoring

Balance Caching

Best Practices

Error Responses

List Transactions

Send Mobile Top-Up

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

OCPay

​Overview

​Response

​Example Request

​Example Response

​Use Cases

Pre-Transaction Check

Balance Display

Low Balance Alerts

Financial Reports

​Integration Examples

​Pre-Transaction Validation

​Balance Monitoring

​Balance Caching

​Best Practices

​Error Responses

​Related Endpoints

List Transactions

Send Mobile Top-Up

Overview

Response

Example Request

Example Response

Use Cases

Integration Examples

Pre-Transaction Validation

Balance Monitoring

Balance Caching

Best Practices

Error Responses

Related Endpoints