Inter API Documentation

# GetPartnerBalance Method

Overview

The GetPartnerBalance method retrieves your current financial standing with Inter, including your current balance, pending credits/charges, and available operating credit. This information is essential for managing your cash flow and ensuring you have sufficient funds to process new orders.

Use Cases

• Pre-Transaction Check: Verify available credit before creating orders
• Financial Monitoring: Track your account balance in real-time
• Cash Flow Management: Monitor pending credits and charges
• Automated Alerts: Set up alerts when balance falls below threshold
• Reconciliation: Verify balance matches your internal records
• Credit Limit Monitoring: Ensure you stay within operating limits

Response Fields

Understanding the Response

CurrentBalance

Your current account balance with Pontual:

• Positive Balance: You have funds on deposit with Pontual
• Negative Balance: You owe Pontual for orders processed
• Zero Balance: Account is settled

Example:

• CurrentBalance = $5,000 → You have $5,000 on deposit
• CurrentBalance = -$2,000 → You owe Pontual $2,000

Request Fields

SOAP Request/Response Examples

Example 1: Positive Balance with Available Credit

Request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPartnerBalance xmlns="http://tempuri.org/">
      <AgentID>12345</AgentID>
      <PartnerID>67890</PartnerID>
    </GetPartnerBalance>
  </soap:Body>
</soap:Envelope>

Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPartnerBalanceResponse xmlns="http://tempuri.org/">
      <GetPartnerBalanceResult>
        <PartnerBalance>
          <PartnerID>67890</PartnerID>
          <CurrentBalance>5000.00</CurrentBalance>
          <PendingCreditsOrCharges>1000.00</PendingCreditsOrCharges>
          <OperatingCredit>16000.00</OperatingCredit>
        </PartnerBalance>
      </GetPartnerBalanceResult>
    </GetPartnerBalanceResponse>
  </soap:Body>
</soap:Envelope>

Interpretation:

• Current balance: $5,000 (on deposit)
• Pending credits: $1,000 (deposit in transit)
• Operating credit: $16,000 (available to create orders)
• Implied credit limit: $10,000 ($16,000 - $5,000 - $1,000)

Example 2: Negative Balance with Credit Line

Request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPartnerBalance xmlns="http://tempuri.org/">
      <AgentID>12345</AgentID>
      <PartnerID>67890</PartnerID>
    </GetPartnerBalance>
  </soap:Body>
</soap:Envelope>

Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPartnerBalanceResponse xmlns="http://tempuri.org/">
      <GetPartnerBalanceResult>
        <PartnerBalance>
          <PartnerID>67890</PartnerID>
          <CurrentBalance>-2000.00</CurrentBalance>
          <PendingCreditsOrCharges>-500.00</PendingCreditsOrCharges>
          <OperatingCredit>7500.00</OperatingCredit>
        </PartnerBalance>
      </GetPartnerBalanceResult>
    </GetPartnerBalanceResponse>
  </soap:Body>
</soap:Envelope>

Interpretation:

• Current balance: -$2,000 (you owe Pontual)
• Pending charges: -$500 (orders being processed)
• Operating credit: $7,500 (still available to create orders)
• Implied credit limit: $10,000 ($7,500 + $2,000 + $500)

Integration Best Practices

1. Check Balance Before Creating Orders

// Always check balance before creating high-value orders
async function createOrderWithBalanceCheck(orderData) {
  // 1. Get current balance
  const balance = await soapClient.GetPartnerBalance({
    AgentID: config.agentID,
    PartnerID: config.partnerID
  });
  
  // 2. Check if sufficient credit available
  const orderAmount = orderData.netAmountSent + orderData.totalFeeSender;
  
  if (balance.OperatingCredit < orderAmount) {
    throw new Error(
      `Insufficient credit. Available: ${balance.OperatingCredit}, ` +
      `Required: ${orderAmount}. Please deposit funds.`
    );
  }
  
  // 3. Warn if balance is getting low
  if (balance.OperatingCredit < orderAmount * 2) {
    console.warn(
      `⚠️ Low balance warning: Only ${balance.OperatingCredit} available. ` +
      `Consider depositing funds soon.`
    );
  }
  
  // 4. Create order
  const order = await soapClient.CreateNewOrder(orderData);
  
  return order;
}

2. Real-Time Balance Monitoring

// Monitor balance in real-time with caching
class BalanceMonitor {
  constructor() {
    this.cache = null;
    this.cacheTime = null;
    this.cacheTTL = 5 * 60 * 1000; // 5 minutes
    this.lowBalanceThreshold = 1000; // $1,000
    this.criticalBalanceThreshold = 500; // $500
  }
  
  async getBalance(forceRefresh = false) {
    // Use cache if available and not expired
    if (!forceRefresh && this.cache && this.cacheTime) {
      const age = Date.now() - this.cacheTime;
      if (age < this.cacheTTL) {
        return this.cache;
      }
    }
    
    // Fetch fresh balance
    const balance = await soapClient.GetPartnerBalance({
      AgentID: config.agentID,
      PartnerID: config.partnerID
    });
    
    // Update cache
    this.cache = balance;
    this.cacheTime = Date.now();
    
    // Check thresholds
    this.checkThresholds(balance);
    
    return balance;
  }
  
  checkThresholds(balance) {
    if (balance.OperatingCredit <= this.criticalBalanceThreshold) {
      this.alertCriticalBalance(balance);
    } else if (balance.OperatingCredit <= this.lowBalanceThreshold) {
      this.alertLowBalance(balance);
    }
  }
  
  async alertCriticalBalance(balance) {
    console.error(`🚨 CRITICAL: Operating credit is ${balance.OperatingCredit}`);
    
    // Send urgent notification
    await sendEmail({
      to: config.financeEmail,
      subject: '🚨 URGENT: Critical Balance Alert',
      priority: 'high',
      body: `
        Operating credit has fallen to ${balance.OperatingCredit}.
        
        Current Balance: ${balance.CurrentBalance}
        Pending: ${balance.PendingCreditsOrCharges}
        Operating Credit: ${balance.OperatingCredit}
        
        IMMEDIATE ACTION REQUIRED: Deposit funds to avoid order rejections.
      `
    });
    
    // Send SMS to finance team
    await sendSMS(config.financePhone, 
      `URGENT: Operating credit is ${balance.OperatingCredit}. Deposit funds immediately.`
    );
  }
  
  async alertLowBalance(balance) {
    console.warn(`⚠️ WARNING: Operating credit is ${balance.OperatingCredit}`);
    
    // Send warning notification
    await sendEmail({
      to: config.financeEmail,
      subject: '⚠️ Low Balance Warning',
      body: `
        Operating credit is running low: ${balance.OperatingCredit}
        
        Current Balance: ${balance.CurrentBalance}
        Pending: ${balance.PendingCreditsOrCharges}
        Operating Credit: ${balance.OperatingCredit}
        
        Please plan to deposit funds soon.
      `
    });
  }
  
  // Force refresh after creating order
  async invalidateCache() {
    this.cache = null;
    this.cacheTime = null;
  }
}

// Usage
const balanceMonitor = new BalanceMonitor();

// Check balance before order
const balance = await balanceMonitor.getBalance();
console.log(`Available credit: ${balance.OperatingCredit}`);

// After creating order, invalidate cache
await createOrder(orderData);
await balanceMonitor.invalidateCache();

3. Daily Balance Report

// Generate daily balance report
async function generateDailyBalanceReport() {
  const balance = await soapClient.GetPartnerBalance({
    AgentID: config.agentID,
    PartnerID: config.partnerID
  });
  
  // Get yesterday's balance from database
  const yesterday = new Date();
  yesterday.setDate(yesterday.getDate() - 1);
  const yesterdayBalance = await db.balanceHistory.findOne({
    date: yesterday.toISOString().split('T')[0]
  });
  
  // Calculate change
  const change = yesterdayBalance 
    ? balance.CurrentBalance - yesterdayBalance.currentBalance
    : 0;
  
  const report = {
    date: new Date().toISOString().split('T')[0],
    currentBalance: balance.CurrentBalance,
    pendingCreditsOrCharges: balance.PendingCreditsOrCharges,
    operatingCredit: balance.OperatingCredit,
    changeFromYesterday: change,
    status: getBalanceStatus(balance.OperatingCredit)
  };
  
  // Save to database
  await db.balanceHistory.insert(report);
  
  // Send email report
  await sendEmail({
    to: config.financeEmail,
    subject: `Daily Balance Report - ${report.date}`,
    html: `
      <h2>Daily Balance Report</h2>
      <table>
        <tr>
          <td><strong>Date:</strong></td>
          <td>${report.date}</td>
        </tr>
        <tr>
          <td><strong>Current Balance:</strong></td>
          <td>${balance.CurrentBalance.toFixed(2)}</td>
        </tr>
        <tr>
          <td><strong>Pending Credits/Charges:</strong></td>
          <td>${balance.PendingCreditsOrCharges.toFixed(2)}</td>
        </tr>
        <tr>
          <td><strong>Operating Credit:</strong></td>
          <td style="font-size: 18px; font-weight: bold;">
            ${balance.OperatingCredit.toFixed(2)}
          </td>
        </tr>
        <tr>
          <td><strong>Change from Yesterday:</strong></td>
          <td style="color: ${change >= 0 ? 'green' : 'red'};">
            ${change >= 0 ? '+' : ''}${change.toFixed(2)}
          </td>
        </tr>
        <tr>
          <td><strong>Status:</strong></td>
          <td style="color: ${getBalanceStatusColor(report.status)};">
            ${report.status}
          </td>
        </tr>
      </table>
    `
  });
  
  return report;
}

function getBalanceStatus(operatingCredit) {
  if (operatingCredit >= 5000) return 'HEALTHY';
  if (operatingCredit >= 1000) return 'GOOD';
  if (operatingCredit >= 500) return 'LOW';
  return 'CRITICAL';
}

function getBalanceStatusColor(status) {
  const colors = {
    'HEALTHY': 'green',
    'GOOD': 'blue',
    'LOW': 'orange',
    'CRITICAL': 'red'
  };
  return colors[status] || 'gray';
}

// Run daily at 9:00 AM
// cron.schedule('0 9 * * *', generateDailyBalanceReport);

4. Automatic Deposit Alerts

// Set up automatic alerts based on balance thresholds
class AutomaticDepositAlerts {
  constructor() {
    this.thresholds = [
      { amount: 500, severity: 'CRITICAL', notified: false },
      { amount: 1000, severity: 'HIGH', notified: false },
      { amount: 2500, severity: 'MEDIUM', notified: false },
      { amount: 5000, severity: 'LOW', notified: false }
    ];
  }
  
  async checkAndAlert() {
    const balance = await soapClient.GetPartnerBalance({
      AgentID: config.agentID,
      PartnerID: config.partnerID
    });
    
    // Check each threshold
    for (const threshold of this.thresholds) {
      if (balance.OperatingCredit <= threshold.amount && !threshold.notified) {
        await this.sendAlert(threshold, balance);
        threshold.notified = true;
      } else if (balance.OperatingCredit > threshold.amount && threshold.notified) {
        // Reset notification flag when balance recovers
        threshold.notified = false;
      }
    }
  }
  
  async sendAlert(threshold, balance) {
    const message = {
      CRITICAL: `🚨 URGENT: Operating credit has fallen to ${balance.OperatingCredit}. Deposit funds immediately!`,
      HIGH: `⚠️ HIGH PRIORITY: Operating credit is ${balance.OperatingCredit}. Please deposit funds today.`,
      MEDIUM: `⚠️ Operating credit is ${balance.OperatingCredit}. Consider depositing funds this week.`,
      LOW: `ℹ️ Operating credit is ${balance.OperatingCredit}. Monitor balance closely.`
    };
    
    await sendEmail({
      to: config.financeEmail,
      subject: `${threshold.severity} Balance Alert - ${balance.OperatingCredit}`,
      body: message[threshold.severity]
    });
    
    // For critical alerts, also send SMS
    if (threshold.severity === 'CRITICAL') {
      await sendSMS(config.financePhone, message[threshold.severity]);
    }
  }
}

// Run every 30 minutes
const depositAlerts = new AutomaticDepositAlerts();
// setInterval(() => depositAlerts.checkAndAlert(), 30 * 60 * 1000);

Testing

Related Methods

Before calling GetPartnerBalance:

• No prerequisites

After getting balance:

• CreateNewOrder - Create orders if sufficient credit
• GetPaymentsByDate - Reconcile payments

Support

• remittance@inter.co
• marcos.lanzoni@inter.co