Skip to main content
GET
https://api.sandbox.wepayout.com.br
/
v2
/
account
/
{merchantId}
/
balance
/
history
Get Balance Specific Day
curl --request GET \
  --url https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/balance/history \
  --header 'Authorization: Bearer <token>'
{
  "balance": 15000,
  "available_balance": 10000,
  "reserve_balance": 0,
  "fee": null
}

​
Get Balance Specific Day

Check what the account balance was on a specific day.

​
Path Parameters

​
merchantId
string
required
Merchant ID

​
Query Parameters

​
currency
string
Currency code of your deposit account. If not provided, the default value will be DRE.Allowed values: USD, AUD, EUR, GBP, BRL, CAD, CHFExample: BRL
​
recipient_id
string
ID of your recipientExample: 12
​
date
string
required
Enter the date in the following format: YYYY-MM-DDExample: 2024-01-15

​
Response

​
balance
number
Example: 15000
​
available_balance
number
Example: 10000
​
reserve_balance
number
Example: 0
​
fee
number or null
This field will only be different from null when the account is configured to receive fees in a wallet. Other than in this case, the balance of the other fee account(wallet) that will receive the fees is returned.Default: nullExample: 100

​
Request Example

curl --request GET \
  --url 'https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/balance/history'?date=2025-01-15 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {token}'

{
  "balance": 15000,
  "available_balance": 10000,
  "reserve_balance": 0,
  "fee": null
}

​
Use Cases

Track balance changes over time for reporting and reconciliation:
async function getBalanceHistory(merchantId, startDate, endDate) {
  const dates = generateDateRange(startDate, endDate);
  const history = [];
  
  for (const date of dates) {
    const balance = await getBalanceSpecificDay(merchantId, date);
    history.push({ date, ...balance });
  }
  
  return history;
}
Verify end-of-day balances for accounting purposes:
async function reconcileEndOfDay(merchantId, date) {
  const balance = await getBalanceSpecificDay(merchantId, date);
  const transactions = await getTransactionsForDay(merchantId, date);
  
  // Compare calculated vs actual balance
  const calculatedBalance = calculateBalance(transactions);
  const difference = balance.balance - calculatedBalance;
  
  if (difference !== 0) {
    console.warn(`Reconciliation mismatch: ${difference}`);
  }
  
  return { balance, transactions, difference };
}
Generate balance reports for specific periods:
async function generateMonthlyReport(merchantId, year, month) {
  const daysInMonth = new Date(year, month, 0).getDate();
  const report = [];
  
  for (let day = 1; day <= daysInMonth; day++) {
    const date = `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
    const balance = await getBalanceSpecificDay(merchantId, date);
    report.push({ date, balance: balance.balance });
  }
  
  return report;
}
Create an audit trail of balance changes:
async function auditBalanceChanges(merchantId, dates) {
  const audit = [];
  
  for (let i = 0; i < dates.length - 1; i++) {
    const currentBalance = await getBalanceSpecificDay(merchantId, dates[i]);
    const nextBalance = await getBalanceSpecificDay(merchantId, dates[i + 1]);
    
    const change = nextBalance.balance - currentBalance.balance;
    
    audit.push({
      date: dates[i],
      balance: currentBalance.balance,
      change: change,
      percentChange: (change / currentBalance.balance) * 100
    });
  }
  
  return audit;
}

​
Date Format

The date parameter must be in the format YYYY-MM-DD:
  • ✅ Valid: 2024-01-15
  • ✅ Valid: 2023-12-31
  • ❌ Invalid: 15/01/2024
  • ❌ Invalid: 01-15-2024
  • ❌ Invalid: 2024/01/15

​
Response Fields

​
balance

The total balance in the account on the specified date.

​
available_balance

The balance available for withdrawal or transactions on the specified date.

​
reserve_balance

The amount held in reserve on the specified date (if applicable).

​
fee

Fee balance on the specified date (only applicable when the account is configured to receive fees in a wallet).

​
Best Practices

Historical Data Availability: Balance history is typically available for the past 90 days. Check with your account manager for specific data retention policies.
Rate Limiting: When querying multiple dates, implement rate limiting to avoid hitting API limits. Consider batching requests or adding delays between calls.
Caching: Historical balance data doesn’t change. Cache responses indefinitely to improve performance and reduce API calls.

​
Integration Example

class BalanceHistoryService {
  constructor(apiKey, merchantId) {
    this.apiKey = apiKey;
    this.merchantId = merchantId;
    this.baseUrl = 'https://api.wepayments.com/v2';
    this.cache = new Map();
  }
  
  async getBalanceForDate(date, currency = 'BRL', recipientId = null) {
    const cacheKey = `${date}-${currency}-${recipientId}`;
    
    // Check cache first
    if (this.cache.has(cacheKey)) {
      return this.cache.get(cacheKey);
    }
    
    const params = new URLSearchParams({ date });
    if (currency) params.append('currency', currency);
    if (recipientId) params.append('recipient_id', recipientId);
    
    const url = `${this.baseUrl}/account/${this.merchantId}/balance/history?${params}`;
    
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Accept': 'application/json'
      }
    });
    
    const data = await response.json();
    
    // Cache the result
    this.cache.set(cacheKey, data);
    
    return data;
  }
  
  async getBalanceRange(startDate, endDate, currency = 'BRL') {
    const dates = this.generateDateRange(startDate, endDate);
    const balances = [];
    
    for (const date of dates) {
      const balance = await this.getBalanceForDate(date, currency);
      balances.push({ date, ...balance });
      
      // Add small delay to avoid rate limiting
      await this.delay(100);
    }
    
    return balances;
  }
  
  generateDateRange(startDate, endDate) {
    const dates = [];
    const current = new Date(startDate);
    const end = new Date(endDate);
    
    while (current <= end) {
      dates.push(current.toISOString().split('T')[0]);
      current.setDate(current.getDate() + 1);
    }
    
    return dates;
  }
  
  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
  
  async getMonthEndBalances(year, currency = 'BRL') {
    const balances = [];
    
    for (let month = 1; month <= 12; month++) {
      const lastDay = new Date(year, month, 0).getDate();
      const date = `${year}-${String(month).padStart(2, '0')}-${String(lastDay).padStart(2, '0')}`;
      
      const balance = await this.getBalanceForDate(date, currency);
      balances.push({
        month: new Date(year, month - 1).toLocaleString('default', { month: 'long' }),
        date,
        ...balance
      });
    }
    
    return balances;
  }
}

// Usage
const historyService = new BalanceHistoryService('YOUR_API_KEY', 'MERCHANT_ID');

// Get balance for a specific date
const balance = await historyService.getBalanceForDate('2024-01-15');
console.log('Balance on 2024-01-15:', balance.balance);

// Get balance range
const rangeBalances = await historyService.getBalanceRange('2024-01-01', '2024-01-31');
console.log('January balances:', rangeBalances);

// Get month-end balances for the year
const yearEndBalances = await historyService.getMonthEndBalances(2024);
console.log('Year-end balances:', yearEndBalances);

​
Error Handling

​
Invalid Date Format

{
  "error": "Invalid date format. Use YYYY-MM-DD"
}

​
Future Date

{
  "error": "Cannot retrieve balance for future dates"
}

​
Date Out of Range

{
  "error": "Balance history not available for the specified date"
}