Skip to main content

Get Wallet Balance

Retrieve your current wallet balances across all currencies to check available funds for placing orders. Delivery Partners (DPs) can have multiple wallets, one for each supported currency (AED, INR, SGD, USD), allowing for multi-currency transactions and balance management.

Endpoint​

GET /v1/delivery-partners/{dpID}/wallet/balance

Headers​

HeaderTypeDescriptionRequired
x-client-idStringYour clientID✅ Yes
x-client-secretStringYour clientSecret✅ Yes

Path Parameters​

ParameterTypeDescriptionRequired
dpIDStringYour delivery partner ID✅ Yes

Example Request​

curl --location 'https://stage-platform-exlr8.exlr8now.com/v1/delivery-partners/YOUR_DP_ID/wallet/balance' \
  --header 'x-client-id: YOUR_CLIENT_ID' \
  --header 'x-client-secret: YOUR_CLIENT_SECRET'

Response​

Successful Response​

[
  {
    "walletID": "bd0e1528-1171-48c7-841b-4186010b4c06",
    "currency": "AED",
    "balance": 42345.9874
  },
  {
    "walletID": "dee25d63-b110-48ee-9140-e9bf1649a06b",
    "currency": "INR",
    "balance": 12498908.2263
  },
  {
    "walletID": "d9e04ac6-9ce8-436c-858e-a86989610620",
    "currency": "SGD",
    "balance": 960.462
  },
  {
    "walletID": "ab7d7384-1284-4971-a3d6-3b50d3036a16",
    "currency": "USD",
    "balance": 707.9619
  }
]

Get Selected Wallet Balance​

You can also retrieve only your selected wallet balance by adding the selectedWallet=true query parameter. This is useful when you only need the balance of your currently selected wallet.

Example Request​

curl --location 'https://stage-platform-exlr8.exlr8now.com/v1/delivery-partners/YOUR_DP_ID/wallet/balance?selectedWallet=true' \
  --header 'x-client-id: YOUR_CLIENT_ID' \
  --header 'x-client-secret: YOUR_CLIENT_SECRET'

Successful Response​

[
  {
    "walletID": "dee25d63-b110-48ee-9140-e9bf1649a06b",
    "currency": "INR",
    "balance": 12498908.2263
  }
]
Selected Wallet

This endpoint returns an array with a single wallet object representing your currently selected wallet. Use this when you need to quickly check your primary wallet balance without fetching all wallets.

Response Fields​

FieldTypeDescription
walletIDStringUnique identifier for the wallet
currencyStringCurrency code (AED, INR, SGD, or USD)
balanceNumberCurrent wallet balance in the specified currency

Multi-Currency Wallet System​

Supported Currencies​

DPs can have up to four wallets, one for each supported currency:

  • AED (United Arab Emirates Dirham)
  • INR (Indian Rupee)
  • SGD (Singapore Dollar)
  • USD (United States Dollar)

Wallet Management​

  • Each currency has its own dedicated wallet
  • Balances are maintained separately per currency
  • Transactions are processed in the appropriate currency wallet
  • DPs can select a primary wallet for default transactions (see Select Wallet)

Balance Monitoring​

Real-time Balance Checks​

// Example: Check balance before placing order
async function checkBalanceBeforeOrder(orderAmount, currency) {
  try {
    const response = await fetch(
      `${baseUrl}/v1/delivery-partners/${dpID}/wallet/balance`,
      {
        headers: {
          "x-client-id": clientId,
          "x-client-secret": clientSecret,
        },
      }
    );

    const wallets = await response.json();
    const wallet = wallets.find((w) => w.currency === currency);

    if (!wallet) {
      throw new Error(`No wallet found for currency: ${currency}`);
    }

    if (wallet.balance >= orderAmount) {
      console.log(`Sufficient balance in ${currency}: ${wallet.balance}`);
      return true;
    } else {
      console.warn(
        `Insufficient balance in ${currency}. Available: ${wallet.balance}, Required: ${orderAmount}`
      );
      return false;
    }
  } catch (error) {
    console.error("Error checking wallet balance:", error);
    throw error;
  }
}

Balance Alerts​

// Example: Set up balance monitoring for all currencies
async function monitorAllBalances(
  thresholds = { INR: 10000, USD: 100, SGD: 100, AED: 1000 }
) {
  const wallets = await getWalletBalances();

  for (const wallet of wallets) {
    const threshold = thresholds[wallet.currency];
    if (wallet.balance < threshold) {
      await sendLowBalanceAlert({
        currency: wallet.currency,
        currentBalance: wallet.balance,
        threshold: threshold,
        walletID: wallet.walletID,
      });
    }
  }
}

Error Responses​

Unauthorized Access​

{
  "error": "unauthenticated",
  "errCode": "UNAUTHORIZED"
}

Invalid DP ID​

{
  "error": "forbidden: param: admin user does not have access to DP: INVALID_DP_ID",
  "errCode": "FORBIDDEN"
}

Use Cases​

1. Pre-order Validation​

Check balance in the required currency before allowing customers to place orders.

2. Dashboard Display​

Show current balances across all currencies on admin dashboards.

3. Low Balance Alerts​

Monitor balances in each currency and alert when funds are running low.

4. Financial Reporting​

Include balance information across currencies in financial reports.

5. Currency Selection​

Choose the appropriate wallet based on order currency and available balances.

Best Practices​

  1. Check Before Orders: Always verify sufficient balance in the required currency before placing orders
  2. Cache Wisely: Balance changes frequently, so cache for short periods only
  3. Handle Errors: Implement proper error handling for balance checks
  4. Monitor Regularly: Set up automated balance monitoring for all currencies
  5. Alert Thresholds: Configure low balance alerts for each currency based on your business needs
  6. Currency Matching: Ensure order currency matches available wallet currencies

Integration Patterns​

Pre-order Balance Check​

// Recommended pattern: Check balance before order
async function placeOrderWithBalanceCheck(orderData) {
  // 1. Calculate order total and currency
  const { total: orderTotal, currency: orderCurrency } =
    calculateOrderTotal(orderData);

  // 2. Check wallet balance for the specific currency
  const hasBalance = await checkBalanceBeforeOrder(orderTotal, orderCurrency);

  if (!hasBalance) {
    throw new Error(`Insufficient wallet balance in ${orderCurrency}`);
  }

  // 3. Place order
  return await placeOrder(orderData);
}

Balance Monitoring Service​

// Example: Background balance monitoring for all currencies
class WalletMonitor {
  constructor(dpID, clientId, clientSecret, thresholds) {
    this.dpID = dpID;
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.thresholds = thresholds; // e.g., { INR: 10000, USD: 100, SGD: 100, AED: 1000 }
  }

  async startMonitoring(intervalMinutes = 30) {
    setInterval(async () => {
      try {
        const wallets = await this.getBalances();
        await this.checkAllThresholds(wallets);
      } catch (error) {
        console.error("Balance monitoring error:", error);
      }
    }, intervalMinutes * 60 * 1000);
  }

  async getBalances() {
    const response = await fetch(
      `${baseUrl}/v1/delivery-partners/${this.dpID}/wallet/balance`,
      {
        headers: {
          "x-client-id": this.clientId,
          "x-client-secret": this.clientSecret,
        },
      }
    );

    return await response.json();
  }

  async checkAllThresholds(wallets) {
    for (const wallet of wallets) {
      const threshold = this.thresholds[wallet.currency];
      if (threshold && wallet.balance < threshold) {
        const level = wallet.balance < threshold * 0.5 ? "CRITICAL" : "WARNING";
        await this.sendAlert(level, wallet);
      }
    }
  }

  async sendAlert(level, wallet) {
    // Implement alert sending logic (email, Slack, etc.)
    console.log(
      `${level} balance alert for ${wallet.currency}: ${wallet.balance}`
    );
  }
}