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

Header	Type	Description	Required
x-client-id	String	Your clientID	✅ Yes
x-client-secret	String	Your clientSecret	✅ Yes

Path Parameters

Parameter	Type	Description	Required
dpID	String	Your 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

Field	Type	Description
walletID	String	Unique identifier for the wallet
currency	String	Currency code (AED, INR, SGD, or USD)
balance	Number	Current 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}`
    );
  }
}

Related Endpoints

• Select Wallet - Choose a primary wallet for transactions
• Get Wallet Transactions - View transaction history
• Place Order - Orders will debit from the appropriate currency wallet