Skip to main content

Query Dedicated Funds Card Balance

Overview​

Use this endpoint to query the available balance of a Dedicated Funds Card. This endpoint is specifically for Dedicated Funds Cards only (cards with their own independent balance). For Shared Funds Cards, balances are managed through budget accounts instead.

NOTE: This API is offered on a client-by-client approval basis. Speak to your account manager to check eligibility.

IMPORTANT: This endpoint only works for Dedicated Funds Cards. It will not work for Shared Funds Cards.

Resource Access​

Production (api.ahrvo.network)

GET https://api.ahrvo.network/card/issuance/api/issuing/card/v2/normal/balance

Staging (gateway.ahrvo.network)

GET https://gateway.ahrvo.network/card/issuance/api/issuing/card/v2/normal/balance

Request Headers​

HeaderValueRequiredDescription
Acceptapplication/jsonYesContent type for the response
AuthorizationBearer {access_token}YesBearer token for authentication
x-api-keyAPI KeyYesAPI key for authentication

Query Parameters​

ParameterTypeRequiredDescription
card_idstringYesA unique ID of the card

Response​

Success Response (200 OK)​

{
"code": "SUCCESS",
"data": {
"card_number": "5157********2686",
"available_balance": "1468.87"
}
}

Response Fields​

FieldTypeDescription
codestringStatus string indicating the result. "SUCCESS" refers to a successful query
dataobjectResponse data object
data.card_numberstringMasked card number (e.g., 5157****8888)
data.available_balancestringAvailable balance of the Dedicated Funds Card (in USD)

Error Responses​

  • 400 Bad Request: Invalid card_id or card is not a Dedicated Funds Card
  • 401 Unauthorized: Invalid or missing authentication token
  • 403 Forbidden: Card issuance feature not enabled for this account
  • 404 Not Found: Card does not exist

Code Examples​

cURL​

curl -X GET \
'https://gateway.ahrvo.network/card/issuance/api/issuing/card/v2/normal/balance?card_id=card201907021723076245' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'x-api-key: YOUR_API_KEY'

Python​

import requests

url = "https://gateway.ahrvo.network/card/issuance/api/issuing/card/v2/normal/balance"
headers = {
"Accept": "application/json",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"x-api-key": "YOUR_API_KEY"
}
params = {
"card_id": "card201907021723076245"
}

response = requests.get(url, headers=headers, params=params)
result = response.json()

if result['code'] == 'SUCCESS':
data = result['data']

print(f"Card Balance Information:")
print(f" Card Number: {data['card_number']}")
print(f" Available Balance: ${data['available_balance']}")
else:
print(f"Failed to query balance: {result}")

JavaScript (Node.js)​

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/card/issuance/api/issuing/card/v2/normal/balance';
const headers = {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'x-api-key': 'YOUR_API_KEY'
};
const params = {
card_id: 'card201907021723076245'
};

axios.get(url, { headers, params })
.then(response => {
const result = response.data;

if (result.code === 'SUCCESS') {
const data = result.data;

console.log('Card Balance Information:');
console.log(` Card Number: ${data.card_number}`);
console.log(` Available Balance: $${data.available_balance}`);
}
})
.catch(error => {
console.error('Failed to query balance:', error.response.data);
});

Usage Notes​

  • Dedicated Funds Only: This endpoint only works for Dedicated Funds Cards
  • Real-Time Balance: Returns the current available balance
  • Currency: Balance is returned in the card's billing currency
  • Masked Card Number: Card number is masked for security
  • Balance Updates: Balance reflects recent transactions (may have slight delays during processing)

Common Use Cases​

Check Card Balance Before Transaction​

Verify sufficient balance before attempting a transaction:

def check_balance_before_transaction(card_id, transaction_amount):
"""
Check if card has sufficient balance for a transaction
"""
print(f"\nChecking balance for transaction of ${transaction_amount:.2f}...\n")

response = query_dedicated_funds_card_balance(card_id)

if response['code'] == 'SUCCESS':
data = response['data']
available_balance = float(data['available_balance'])

print(f"Card: {data['card_number']}")
print(f"Available Balance: ${available_balance:.2f}")
print(f"Transaction Amount: ${transaction_amount:.2f}")

if available_balance >= transaction_amount:
remaining = available_balance - transaction_amount
print(f"\n✓ Sufficient balance")
print(f" Balance after transaction: ${remaining:.2f}")

return {
'sufficient': True,
'available_balance': available_balance,
'remaining_after': remaining
}
else:
shortage = transaction_amount - available_balance
print(f"\n✗ Insufficient balance")
print(f" Shortage: ${shortage:.2f}")
print(f" Top-up required: ${shortage:.2f}")

return {
'sufficient': False,
'available_balance': available_balance,
'shortage': shortage
}
else:
print(f"Failed to check balance: {response}")
return {
'sufficient': False,
'error': response
}

# Example usage
check_result = check_balance_before_transaction('card201907021723076245', 500.00)

if check_result['sufficient']:
print("\nProceed with transaction")
else:
print(f"\nTop-up card with ${check_result['shortage']:.2f} before transaction")

Monitor Multiple Card Balances​

Check balances for multiple Dedicated Funds Cards:

async function monitorCardBalances(cardIds) {
console.log('\n=== Card Balance Monitoring ===\n');

const balances = [];
let totalBalance = 0;
let lowBalanceCards = [];

for (const cardId of cardIds) {
try {
const response = await queryDedicatedFundsCardBalance(cardId);

if (response.code === 'SUCCESS') {
const data = response.data;
const balance = parseFloat(data.available_balance);

balances.push({
card_id: cardId,
card_number: data.card_number,
balance: balance
});

totalBalance += balance;

// Display card balance
console.log(`Card: ${data.card_number}`);
console.log(` Balance: $${balance.toFixed(2)}`);

// Check for low balance (less than $100)
if (balance < 100) {
console.log(` ⚠️ LOW BALANCE WARNING\n`);
lowBalanceCards.push({
card_id: cardId,
card_number: data.card_number,
balance: balance
});
} else if (balance < 500) {
console.log(` ⚡ Medium balance\n`);
} else {
console.log(` ✓ Good balance\n`);
}
} else {
console.log(`Card ${cardId}: Failed to query balance\n`);
}
} catch (error) {
console.error(`Error querying ${cardId}:`, error.message, '\n');
}
}

// Summary
console.log('=== Summary ===');
console.log(`Total Cards: ${balances.length}`);
console.log(`Total Balance: $${totalBalance.toFixed(2)}`);
console.log(`Average Balance: $${(totalBalance / balances.length).toFixed(2)}`);

if (lowBalanceCards.length > 0) {
console.log(`\n⚠️ Low Balance Alerts: ${lowBalanceCards.length} card(s)`);
lowBalanceCards.forEach(card => {
console.log(` • ${card.card_number}: $${card.balance.toFixed(2)}`);
});
}

return {
balances: balances,
total_balance: totalBalance,
low_balance_cards: lowBalanceCards
};
}

// Example usage
const cardIds = [
'card201907021723076245',
'card201907021723076246',
'card201907021723076247'
];

const report = await monitorCardBalances(cardIds);

Balance Alert System​

Set up automated alerts for low balances:

def setup_balance_alerts(cards, thresholds):
"""
Monitor card balances and send alerts when below thresholds

Args:
cards: List of card IDs to monitor
thresholds: Dict with 'critical', 'warning', 'low' threshold amounts
"""
print("\n=== Balance Alert System ===\n")
print(f"Monitoring {len(cards)} card(s)")
print(f"Thresholds:")
print(f" Critical: Below ${thresholds['critical']:.2f}")
print(f" Warning: Below ${thresholds['warning']:.2f}")
print(f" Low: Below ${thresholds['low']:.2f}\n")

alerts = {
'critical': [],
'warning': [],
'low': [],
'normal': []
}

for card_id in cards:
try:
response = query_dedicated_funds_card_balance(card_id)

if response['code'] == 'SUCCESS':
data = response['data']
balance = float(data['available_balance'])

# Determine alert level
if balance <= thresholds['critical']:
level = 'critical'
icon = '🔴'
status = 'CRITICAL'
elif balance <= thresholds['warning']:
level = 'warning'
icon = '🟡'
status = 'WARNING'
elif balance <= thresholds['low']:
level = 'low'
icon = '🟠'
status = 'LOW'
else:
level = 'normal'
icon = '🟢'
status = 'NORMAL'

card_info = {
'card_id': card_id,
'card_number': data['card_number'],
'balance': balance,
'status': status
}

alerts[level].append(card_info)

print(f"{icon} {data['card_number']}: ${balance:.2f} - {status}")

# Send alerts for critical/warning
if level in ['critical', 'warning']:
send_balance_alert(card_info, level, thresholds)

except Exception as e:
print(f"✗ Error checking {card_id}: {e}")

# Summary
print(f"\n=== Alert Summary ===")
print(f"🔴 Critical: {len(alerts['critical'])} card(s)")
print(f"🟡 Warning: {len(alerts['warning'])} card(s)")
print(f"🟠 Low: {len(alerts['low'])} card(s)")
print(f"🟢 Normal: {len(alerts['normal'])} card(s)")

if alerts['critical']:
print(f"\n🚨 URGENT: {len(alerts['critical'])} card(s) require immediate top-up:")
for card in alerts['critical']:
print(f" • {card['card_number']}: ${card['balance']:.2f}")

return alerts

def send_balance_alert(card_info, level, thresholds):
"""Send alert notification (email/SMS/Slack)"""
# Implementation depends on your notification system
print(f" 📧 Alert sent for {card_info['card_number']}")

# Example usage
cards_to_monitor = [
'card201907021723076245',
'card201907021723076246',
'card201907021723076247'
]

thresholds = {
'critical': 50.00,
'warning': 100.00,
'low': 250.00
}

alerts = setup_balance_alerts(cards_to_monitor, thresholds)

Balance Reconciliation​

Reconcile card balances against your internal records:

async function reconcileCardBalances(expectedBalances) {
console.log('\n=== Card Balance Reconciliation ===\n');

const discrepancies = [];
let totalDiscrepancy = 0;

for (const expected of expectedBalances) {
try {
const response = await queryDedicatedFundsCardBalance(expected.card_id);

if (response.code === 'SUCCESS') {
const data = response.data;
const actualBalance = parseFloat(data.available_balance);
const expectedBalance = parseFloat(expected.balance);
const difference = actualBalance - expectedBalance;

console.log(`Card: ${data.card_number}`);
console.log(` Expected: $${expectedBalance.toFixed(2)}`);
console.log(` Actual: $${actualBalance.toFixed(2)}`);

if (Math.abs(difference) > 0.01) { // Allow 1 cent tolerance
console.log(` ⚠️ DISCREPANCY: $${difference.toFixed(2)}\n`);

discrepancies.push({
card_id: expected.card_id,
card_number: data.card_number,
expected: expectedBalance,
actual: actualBalance,
difference: difference
});

totalDiscrepancy += Math.abs(difference);
} else {
console.log(` ✓ MATCHED\n`);
}
} else {
console.log(` ✗ Failed to query balance\n`);
}
} catch (error) {
console.error(`Error reconciling ${expected.card_id}:`, error.message, '\n');
}
}

// Summary
console.log('=== Reconciliation Summary ===');
console.log(`Total Cards Checked: ${expectedBalances.length}`);
console.log(`Discrepancies Found: ${discrepancies.length}`);
console.log(`Total Discrepancy Amount: $${totalDiscrepancy.toFixed(2)}`);

if (discrepancies.length > 0) {
console.log('\n⚠️ Cards with Discrepancies:');
discrepancies.forEach(disc => {
const sign = disc.difference > 0 ? '+' : '';
console.log(` • ${disc.card_number}: ${sign}$${disc.difference.toFixed(2)}`);
console.log(` Expected: $${disc.expected.toFixed(2)}, Actual: $${disc.actual.toFixed(2)}`);
});

console.log('\n💡 Next Steps:');
console.log(' 1. Review recent transactions for discrepant cards');
console.log(' 2. Check for pending transactions');
console.log(' 3. Update internal records if platform is correct');
console.log(' 4. Contact support if discrepancies persist');
} else {
console.log('\n✅ All balances match!');
}

return {
total_checked: expectedBalances.length,
discrepancies: discrepancies,
total_discrepancy: totalDiscrepancy
};
}

// Example usage
const expectedBalances = [
{ card_id: 'card201907021723076245', balance: '1468.87' },
{ card_id: 'card201907021723076246', balance: '2500.00' },
{ card_id: 'card201907021723076247', balance: '850.50' }
];

const reconciliation = await reconcileCardBalances(expectedBalances);

Generate Balance Report​

Create a comprehensive balance report for all Dedicated Funds Cards:

def generate_balance_report(card_ids):
"""
Generate comprehensive balance report
"""
from datetime import datetime

print("\n" + "=" * 70)
print("DEDICATED FUNDS CARD BALANCE REPORT".center(70))
print("=" * 70)
print(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")

balances = []
total_balance = 0
failed_queries = []

for card_id in card_ids:
try:
response = query_dedicated_funds_card_balance(card_id)

if response['code'] == 'SUCCESS':
data = response['data']
balance = float(data['available_balance'])

balances.append({
'card_id': card_id,
'card_number': data['card_number'],
'balance': balance
})

total_balance += balance
else:
failed_queries.append(card_id)
except Exception as e:
print(f"Error querying {card_id}: {e}")
failed_queries.append(card_id)

if not balances:
print("No balance data available\n")
return None

# Sort by balance (highest first)
balances.sort(key=lambda x: x['balance'], reverse=True)

# Display balances
print("Individual Card Balances:")
print("─" * 70)

for idx, card in enumerate(balances, 1):
percentage = (card['balance'] / total_balance * 100) if total_balance > 0 else 0
bar = '█' * int(percentage / 2)

print(f"{idx}. {card['card_number']}")
print(f" Balance: ${card['balance']:,.2f} ({percentage:.1f}%) {bar}")

# Statistics
print(f"\n{'Statistics'.center(70)}")
print("─" * 70)
print(f"Total Cards: {len(balances)}")
print(f"Total Balance: ${total_balance:,.2f}")
print(f"Average Balance: ${(total_balance / len(balances)):,.2f}")
print(f"Highest Balance: ${max(b['balance'] for b in balances):,.2f}")
print(f"Lowest Balance: ${min(b['balance'] for b in balances):,.2f}")

# Distribution
ranges = {
'$0-$100': 0,
'$100-$500': 0,
'$500-$1,000': 0,
'$1,000-$5,000': 0,
'$5,000+': 0
}

for card in balances:
balance = card['balance']
if balance < 100:
ranges['$0-$100'] += 1
elif balance < 500:
ranges['$100-$500'] += 1
elif balance < 1000:
ranges['$500-$1,000'] += 1
elif balance < 5000:
ranges['$1,000-$5,000'] += 1
else:
ranges['$5,000+'] += 1

print(f"\n{'Balance Distribution'.center(70)}")
print("─" * 70)
for range_name, count in ranges.items():
if count > 0:
bar = '█' * (count * 5)
print(f"{range_name.ljust(15)}: {count:2d} cards {bar}")

if failed_queries:
print(f"\n⚠️ Failed to query {len(failed_queries)} card(s):")
for card_id in failed_queries:
print(f" • {card_id}")

print("\n" + "=" * 70 + "\n")

return {
'total_cards': len(balances),
'total_balance': total_balance,
'average_balance': total_balance / len(balances) if balances else 0,
'balances': balances,
'distribution': ranges,
'failed_queries': failed_queries
}

# Example usage
card_list = [
'card201907021723076245',
'card201907021723076246',
'card201907021723076247',
'card201907021723076248',
'card201907021723076249'
]

report = generate_balance_report(card_list)

Balance Threshold Notification​

Notify when balance crosses specific thresholds:

def monitor_balance_thresholds(card_id, thresholds):
"""
Check balance against multiple thresholds and notify

Args:
card_id: Card ID to monitor
thresholds: List of threshold amounts with actions
"""
response = query_dedicated_funds_card_balance(card_id)

if response['code'] == 'SUCCESS':
data = response['data']
balance = float(data['available_balance'])

print(f"\nCard: {data['card_number']}")
print(f"Current Balance: ${balance:.2f}\n")

triggered_actions = []

# Check each threshold
for threshold in sorted(thresholds, key=lambda x: x['amount'], reverse=True):
if balance <= threshold['amount']:
print(f"⚠️ Threshold Triggered: ${threshold['amount']:.2f}")
print(f" Action: {threshold['action']}")
print(f" Priority: {threshold.get('priority', 'NORMAL')}")

triggered_actions.append({
'threshold': threshold['amount'],
'action': threshold['action'],
'priority': threshold.get('priority', 'NORMAL'),
'current_balance': balance
})

if not triggered_actions:
print("✓ All thresholds OK")
else:
print(f"\n{len(triggered_actions)} action(s) triggered")

# Execute highest priority action
if triggered_actions:
highest_priority = max(triggered_actions,
key=lambda x: {'CRITICAL': 3, 'HIGH': 2, 'NORMAL': 1}.get(x['priority'], 0))
execute_threshold_action(card_id, highest_priority)

return {
'card_number': data['card_number'],
'balance': balance,
'triggered_actions': triggered_actions
}
else:
print(f"Failed to check balance: {response}")
return None

def execute_threshold_action(card_id, action):
"""Execute action based on threshold"""
print(f"\nExecuting Action: {action['action']}")

if action['action'] == 'AUTO_TOPUP':
print(f" • Initiating automatic top-up")
# Call top-up endpoint
elif action['action'] == 'NOTIFY_ADMIN':
print(f" • Sending notification to administrator")
# Send notification
elif action['action'] == 'FREEZE_CARD':
print(f" • Freezing card to prevent overdraft")
# Call freeze endpoint

# Example usage
thresholds = [
{'amount': 50.00, 'action': 'NOTIFY_ADMIN', 'priority': 'CRITICAL'},
{'amount': 100.00, 'action': 'AUTO_TOPUP', 'priority': 'HIGH'},
{'amount': 250.00, 'action': 'SEND_WARNING', 'priority': 'NORMAL'}
]

result = monitor_balance_thresholds('card201907021723076245', thresholds)

Best Practices​

  • Regular Monitoring: Check balances regularly to avoid insufficient funds
  • Set Alerts: Implement automated alerts for low balance warnings
  • Pre-Transaction Checks: Always verify balance before large transactions
  • Reconciliation: Regularly reconcile platform balances with internal records
  • Top-Up Automation: Consider automated top-ups for critical cards
  • Dashboard Integration: Display balances in real-time on management dashboards

Understanding Dedicated Funds Cards​

What are Dedicated Funds Cards?​

  • Each card has its own independent balance
  • Not linked to budget accounts
  • Balance must be topped up directly to the card
  • Ideal for prepaid card programs, gift cards, or isolated spending

Dedicated vs Shared Funds Cards​

FeatureDedicated FundsShared Funds
Balance SourceIndividual card balanceBudget account
Spending LimitsBased on available balanceConfigurable limits
Multiple CardsEach card independentMultiple cards share budget
Balance QueryThis endpointQuery budget balance
Top-UpTop-up card directlyTop-up budget account
  • Top-up Dedicated Funds Card - Add funds to a card
  • Withdraw Funds - Remove funds from a card
  • Query Card Details - View complete card information
  • Query Card Funding Orders - View top-up/withdrawal history
  • Create a Card - Issue new Dedicated Funds Cards

Troubleshooting​

Card Not Found (404)​

  • Cause: Invalid card_id or card doesn't exist
  • Solution:
    • Verify the card ID is correct
    • Use Query All Cards to list available cards
    • Check if card was deleted or cancelled

Wrong Card Type (400)​

  • Cause: Attempting to query balance of a Shared Funds Card
  • Solution:
    • This endpoint only works for Dedicated Funds Cards
    • For Shared Funds Cards, query the budget account balance instead
    • Use Query Card Details to check card type

Balance Discrepancy​

  • Cause: Recent transactions may not be immediately reflected
  • Solution:
    • Wait a few seconds and query again
    • Check Query Card Funding Orders for recent transactions
    • Verify all pending transactions have completed

Security Considerations​

  • Access Control: Restrict balance queries to authorized users only
  • Data Privacy: Balance information is sensitive - handle accordingly
  • Audit Logging: Log all balance queries for security auditing
  • Rate Limiting: Implement reasonable query intervals
  • Masked Card Numbers: Card numbers are masked but still handle carefully

Interactive API Explorer​