Query Card Product

Overview

Use this endpoint to query available card products and their specifications. This is essential before creating cards, as you need to provide a valid card_product_code when issuing new cards. Each card product has specific features like card network, billing currency, validity period, and whether it supports withdrawals.

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

Resource Access

Production (api.ahrvo.network)

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

Staging (gateway.ahrvo.network)

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

---

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
x-api-key	API Key	Yes	API key for authentication

Response

Success Response (200 OK)

{
  "code": "SUCCESS",
  "data": [
    {
      "card_net_work": "MasterCard",
      "card_product_code": "T9M34Q",
      "valid_month": 24,
      "allow_withdrawal": true,
      "card_application_fee": "0",
      "billing_currency": "USD",
      "bin_range": "22346703",
      "share": true,
      "name_cn": "USD TEST",
      "name_en": "USD TEST"
    }
  ]
}

Response Fields

Field	Type	Description
code	string	Status string indicating the result. "SUCCESS" refers to a successful query
data	array	List of available card products
data[].card_net_work	string	Card scheme: Visa, Mastercard, or DC (Diners Club)
data[].card_product_code	string	Card product code - Use this when creating a card
data[].valid_month	integer	Card validity period in months (e.g., 24 = 2 years)
data[].allow_withdrawal	boolean	true: Withdrawals allowed; false: Withdrawals not allowed
data[].card_application_fee	string	Fee charged when applying for this card (in billing currency)
data[].billing_currency	string	Card billing currency code (e.g., USD, EUR)
data[].bin_range	string	Bank Identification Number (BIN) range for the card
data[].share	boolean	true: Shared Funds Card; false: Dedicated Funds Card
data[].name_cn	string	Card product name in Chinese
data[].name_en	string	Card product name in English

Error Responses

• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: Card issuance feature not enabled for this account

Code Examples

cURL

curl -X GET \
  'https://gateway.ahrvo.network/card/issuance/api/issuing/card/v2/product' \
  -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/product"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "x-api-key": "YOUR_API_KEY"
}

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

if result['code'] == 'SUCCESS':
    products = result['data']
    
    print(f"Available Card Products: {len(products)}\n")
    
    for product in products:
        print(f"Product: {product['name_en']}")
        print(f"  Code: {product['card_product_code']}")
        print(f"  Network: {product['card_net_work']}")
        print(f"  Currency: {product['billing_currency']}")
        print(f"  Type: {'Shared Funds' if product['share'] else 'Dedicated Funds'}")
        print(f"  Validity: {product['valid_month']} months")
        print(f"  Application Fee: ${product['card_application_fee']}")
        print(f"  Withdrawal: {'Allowed' if product['allow_withdrawal'] else 'Not Allowed'}")
        print(f"  BIN Range: {product['bin_range']}\n")
else:
    print(f"Failed to query products: {result}")

JavaScript (Node.js)

const axios = require('axios');

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

axios.get(url, { headers })
  .then(response => {
    const result = response.data;
    
    if (result.code === 'SUCCESS') {
      const products = result.data;
      
      console.log(`Available Card Products: ${products.length}\n`);
      
      products.forEach(product => {
        console.log(`Product: ${product.name_en}`);
        console.log(`  Code: ${product.card_product_code}`);
        console.log(`  Network: ${product.card_net_work}`);
        console.log(`  Currency: ${product.billing_currency}`);
        console.log(`  Type: ${product.share ? 'Shared Funds' : 'Dedicated Funds'}`);
        console.log(`  Validity: ${product.valid_month} months`);
        console.log(`  Application Fee: $${product.card_application_fee}`);
        console.log(`  Withdrawal: ${product.allow_withdrawal ? 'Allowed' : 'Not Allowed'}`);
        console.log(`  BIN Range: ${product.bin_range}\n`);
      });
    }
  })
  .catch(error => {
    console.error('Failed to query products:', error.response.data);
  });

Usage Notes

• Required for Card Creation: You must provide a valid card_product_code when creating cards
• Product Availability: Available products depend on your account configuration
• Cache Locally: Product information changes infrequently - consider caching
• BIN Range: The BIN (Bank Identification Number) identifies the card issuer
• Card Networks: Different networks may have different acceptance rates globally
• Validity Period: Cards expire after the valid_month period from issuance

Common Use Cases

List Available Card Products

Display all available card products for selection:

def list_available_card_products():
    """
    List all available card products with details
    """
    print("\n=== Available Card Products ===\n")
    
    response = query_card_product()
    
    if response['code'] == 'SUCCESS':
        products = response['data']
        
        if not products:
            print("No card products available\n")
            return None
        
        print(f"Total Products: {len(products)}\n")
        
        # Categorize by network
        by_network = {}
        for product in products:
            network = product['card_net_work']
            if network not in by_network:
                by_network[network] = []
            by_network[network].append(product)
        
        # Display by network
        for network, network_products in by_network.items():
            print(f"🏦 {network} Cards ({len(network_products)} products)")
            print("─" * 70)
            
            for product in network_products:
                card_type = "💳 Shared Funds" if product['share'] else "💰 Dedicated Funds"
                withdrawal = "✓ Withdrawal" if product['allow_withdrawal'] else "✗ No Withdrawal"
                
                print(f"\n  {product['name_en']}")
                print(f"  Code: {product['card_product_code']}")
                print(f"  Type: {card_type}")
                print(f"  Currency: {product['billing_currency']}")
                print(f"  Validity: {product['valid_month']} months")
                print(f"  Fee: ${product['card_application_fee']}")
                print(f"  {withdrawal}")
                print(f"  BIN: {product['bin_range']}")
            
            print()
        
        return {
            'total': len(products),
            'by_network': by_network,
            'products': products
        }
    else:
        print(f"Failed to retrieve products: {response}")
        return None

# Example usage
products = list_available_card_products()

Find Product by Criteria

Find card products matching specific requirements:

async function findProductByCriteria(criteria) {
  console.log('\n=== Finding Card Products ===');
  console.log('Search Criteria:', JSON.stringify(criteria, null, 2), '\n');
  
  try {
    const response = await queryCardProduct();
    
    if (response.code === 'SUCCESS') {
      let products = response.data;
      
      // Filter by criteria
      if (criteria.network) {
        products = products.filter(p => 
          p.card_net_work.toLowerCase().includes(criteria.network.toLowerCase())
        );
      }
      
      if (criteria.currency) {
        products = products.filter(p => 
          p.billing_currency === criteria.currency.toUpperCase()
        );
      }
      
      if (criteria.shared !== undefined) {
        products = products.filter(p => p.share === criteria.shared);
      }
      
      if (criteria.allowWithdrawal !== undefined) {
        products = products.filter(p => p.allow_withdrawal === criteria.allowWithdrawal);
      }
      
      if (criteria.maxFee !== undefined) {
        products = products.filter(p => 
          parseFloat(p.card_application_fee) <= criteria.maxFee
        );
      }
      
      if (criteria.minValidityMonths) {
        products = products.filter(p => 
          p.valid_month >= criteria.minValidityMonths
        );
      }
      
      // Display results
      console.log(`Found ${products.length} matching product(s):\n`);
      
      if (products.length === 0) {
        console.log('No products match your criteria');
        console.log('Try adjusting your search parameters\n');
        return [];
      }
      
      products.forEach((product, index) => {
        console.log(`${index + 1}. ${product.name_en}`);
        console.log(`   Code: ${product.card_product_code}`);
        console.log(`   Network: ${product.card_net_work}`);
        console.log(`   Currency: ${product.billing_currency}`);
        console.log(`   Type: ${product.share ? 'Shared Funds' : 'Dedicated Funds'}`);
        console.log(`   Validity: ${product.valid_month} months`);
        console.log(`   Fee: $${product.card_application_fee}`);
        console.log(`   Withdrawal: ${product.allow_withdrawal ? 'Yes' : 'No'}\n`);
      });
      
      return products;
    } else {
      console.log('Failed to query products:', response);
      return [];
    }
  } catch (error) {
    console.error('Error finding products:', error.message);
    return [];
  }
}

// Example usage - Find USD Shared Funds cards with no fee
const matches = await findProductByCriteria({
  currency: 'USD',
  shared: true,
  maxFee: 0,
  allowWithdrawal: true
});

// Find Visa cards
const visaCards = await findProductByCriteria({
  network: 'Visa',
  minValidityMonths: 24
});

Build Product Selection UI

Create an interactive product selection interface:

def build_product_selection_ui():
    """
    Build interactive product selection with filtering
    """
    print("\n" + "=" * 70)
    print("CARD PRODUCT SELECTOR".center(70))
    print("=" * 70 + "\n")
    
    response = query_card_product()
    
    if response['code'] != 'SUCCESS':
        print("Failed to load products")
        return None
    
    products = response['data']
    
    if not products:
        print("No products available")
        return None
    
    # Display filter options
    print("Available Filters:")
    print("  1. Card Network (Visa, Mastercard, etc.)")
    print("  2. Card Type (Shared/Dedicated Funds)")
    print("  3. Currency")
    print("  4. Withdrawal Support")
    print("  5. Show All Products\n")
    
    # Get unique values
    networks = sorted(set(p['card_net_work'] for p in products))
    currencies = sorted(set(p['billing_currency'] for p in products))
    
    print(f"Available Networks: {', '.join(networks)}")
    print(f"Available Currencies: {', '.join(currencies)}\n")
    
    # For demo, show all products categorized
    print("=" * 70)
    print("ALL AVAILABLE PRODUCTS")
    print("=" * 70 + "\n")
    
    for idx, product in enumerate(products, 1):
        print(f"[{idx}] {product['name_en']}")
        print("─" * 70)
        
        # Basic Info
        print(f"  Product Code: {product['card_product_code']}")
        print(f"  Card Network: {product['card_net_work']}")
        print(f"  Billing Currency: {product['billing_currency']}")
        
        # Card Type
        card_type_icon = "💳" if product['share'] else "💰"
        card_type_text = "Shared Funds Card" if product['share'] else "Dedicated Funds Card"
        print(f"  Card Type: {card_type_icon} {card_type_text}")
        
        # Features
        print(f"\n  Features:")
        print(f"    • Validity: {product['valid_month']} months ({product['valid_month'] // 12} years)")
        print(f"    • Application Fee: ${product['card_application_fee']}")
        
        withdrawal_status = "✓ Supported" if product['allow_withdrawal'] else "✗ Not Supported"
        print(f"    • Balance Withdrawal: {withdrawal_status}")
        
        print(f"    • BIN Range: {product['bin_range']}")
        
        # Recommendations
        print(f"\n  Best For:")
        if product['share']:
            print(f"    • Budget-controlled spending")
            print(f"    • Employee expense cards")
            print(f"    • Department cards with limits")
        else:
            print(f"    • Independent card balances")
            print(f"    • Prepaid card programs")
            print(f"    • Gift cards or rewards")
        
        print()
    
    print("=" * 70)
    print(f"Total Products: {len(products)}")
    print("=" * 70 + "\n")
    
    return products

# Example usage
selected_products = build_product_selection_ui()

Compare Card Products

Compare multiple card products side by side:

async function compareCardProducts(productCodes = null) {
  console.log('\n=== Card Product Comparison ===\n');
  
  try {
    const response = await queryCardProduct();
    
    if (response.code === 'SUCCESS') {
      let products = response.data;
      
      // Filter by specific codes if provided
      if (productCodes && productCodes.length > 0) {
        products = products.filter(p => productCodes.includes(p.card_product_code));
      }
      
      if (products.length === 0) {
        console.log('No products to compare');
        return null;
      }
      
      console.log(`Comparing ${products.length} card products:\n`);
      
      // Create comparison table
      const properties = [
        { key: 'name_en', label: 'Product Name' },
        { key: 'card_product_code', label: 'Product Code' },
        { key: 'card_net_work', label: 'Network' },
        { key: 'billing_currency', label: 'Currency' },
        { key: 'share', label: 'Type', format: v => v ? 'Shared' : 'Dedicated' },
        { key: 'valid_month', label: 'Validity', format: v => `${v} months` },
        { key: 'card_application_fee', label: 'Fee', format: v => `$${v}` },
        { key: 'allow_withdrawal', label: 'Withdrawal', format: v => v ? 'Yes' : 'No' },
        { key: 'bin_range', label: 'BIN Range' }
      ];
      
      console.log('─'.repeat(100));
      console.log('Property'.padEnd(20) + products.map((p, i) => `Product ${i + 1}`.padEnd(25)).join(''));
      console.log('─'.repeat(100));
      
      properties.forEach(prop => {
        const values = products.map(product => {
          const value = product[prop.key];
          return prop.format ? prop.format(value) : value;
        });
        console.log(prop.label.padEnd(20) + values.map(v => String(v).padEnd(25)).join(''));
      });
      
      console.log('─'.repeat(100));
      
      // Analysis
      console.log('\n📊 Comparison Analysis:\n');
      
      // Find best value
      const lowestFee = Math.min(...products.map(p => parseFloat(p.card_application_fee)));
      const longestValidity = Math.max(...products.map(p => p.valid_month));
      
      console.log(`Lowest Fee: $${lowestFee}`);
      console.log(`Longest Validity: ${longestValidity} months (${(longestValidity / 12).toFixed(1)} years)`);
      
      const sharedCount = products.filter(p => p.share).length;
      const dedicatedCount = products.filter(p => !p.share).length;
      
      console.log(`\nCard Types:`);
      console.log(`  Shared Funds: ${sharedCount}`);
      console.log(`  Dedicated Funds: ${dedicatedCount}`);
      
      const withdrawalSupport = products.filter(p => p.allow_withdrawal).length;
      console.log(`\nWithdrawal Support: ${withdrawalSupport}/${products.length} products`);
      
      return {
        products: products,
        analysis: {
          lowest_fee: lowestFee,
          longest_validity: longestValidity,
          shared_count: sharedCount,
          dedicated_count: dedicatedCount,
          withdrawal_support: withdrawalSupport
        }
      };
    } else {
      console.log('Failed to query products');
      return null;
    }
  } catch (error) {
    console.error('Error comparing products:', error.message);
    return null;
  }
}

// Example usage - Compare all products
const comparison = await compareCardProducts();

// Compare specific products
const specificComparison = await compareCardProducts(['T9M34Q', 'ABC123']);

Cache Product Information

Cache product data to reduce API calls:

def get_cached_card_products(cache_duration_hours=24):
    """
    Get card products with caching to reduce API calls
    
    Args:
        cache_duration_hours: How long to cache data (in hours)
    """
    import json
    import os
    from datetime import datetime, timedelta
    
    cache_file = 'card_products_cache.json'
    cache_valid = False
    
    # Check if cache exists and is valid
    if os.path.exists(cache_file):
        with open(cache_file, 'r') as f:
            cache_data = json.load(f)
        
        cache_time = datetime.fromisoformat(cache_data['cached_at'])
        cache_expires = cache_time + timedelta(hours=cache_duration_hours)
        
        if datetime.now() < cache_expires:
            cache_valid = True
            print(f"Using cached data (cached at {cache_time.strftime('%Y-%m-%d %H:%M:%S')})")
            print(f"Cache expires at {cache_expires.strftime('%Y-%m-%d %H:%M:%S')}\n")
            return cache_data['products']
    
    # Fetch fresh data
    print("Fetching fresh card product data from API...")
    response = query_card_product()
    
    if response['code'] == 'SUCCESS':
        products = response['data']
        
        # Save to cache
        cache_data = {
            'cached_at': datetime.now().isoformat(),
            'products': products
        }
        
        with open(cache_file, 'w') as f:
            json.dump(cache_data, f, indent=2)
        
        print(f"Cached {len(products)} products\n")
        return products
    else:
        print("Failed to fetch products")
        
        # Return stale cache if available
        if os.path.exists(cache_file):
            print("Using stale cache data...")
            with open(cache_file, 'r') as f:
                cache_data = json.load(f)
            return cache_data['products']
        
        return None

# Example usage
products = get_cached_card_products(cache_duration_hours=24)

# Force refresh by deleting cache
import os
if os.path.exists('card_products_cache.json'):
    os.remove('card_products_cache.json')
products = get_cached_card_products()

Product Recommendation Engine

Recommend the best card product based on requirements:

async function recommendCardProduct(requirements) {
  console.log('\n=== Card Product Recommendation Engine ===\n');
  console.log('Your Requirements:', JSON.stringify(requirements, null, 2), '\n');
  
  try {
    const response = await queryCardProduct();
    
    if (response.code === 'SUCCESS') {
      const products = response.data;
      const scoredProducts = [];
      
      products.forEach(product => {
        let score = 0;
        const reasons = [];
        
        // Score based on requirements
        
        // Preferred network
        if (requirements.preferredNetwork) {
          if (product.card_net_work.toLowerCase() === requirements.preferredNetwork.toLowerCase()) {
            score += 10;
            reasons.push(`✓ Matches preferred network (${requirements.preferredNetwork})`);
          }
        }
        
        // Currency match
        if (requirements.currency) {
          if (product.billing_currency === requirements.currency.toUpperCase()) {
            score += 10;
            reasons.push(`✓ Matches required currency (${requirements.currency})`);
          } else {
            score -= 5;
            reasons.push(`⚠ Different currency (${product.billing_currency})`);
          }
        }
        
        // Card type preference
        if (requirements.shared !== undefined) {
          if (product.share === requirements.shared) {
            score += 10;
            reasons.push(`✓ Matches card type preference`);
          }
        }
        
        // Withdrawal requirement
        if (requirements.requireWithdrawal) {
          if (product.allow_withdrawal) {
            score += 5;
            reasons.push('✓ Supports withdrawal');
          } else {
            score -= 10;
            reasons.push('✗ Does not support withdrawal (required)');
          }
        }
        
        // Fee consideration
        const fee = parseFloat(product.card_application_fee);
        if (fee === 0) {
          score += 5;
          reasons.push('✓ No application fee');
        } else if (requirements.maxFee && fee <= requirements.maxFee) {
          score += 2;
          reasons.push(`✓ Fee within budget ($${fee})`);
        } else if (requirements.maxFee && fee > requirements.maxFee) {
          score -= 5;
          reasons.push(`⚠ Fee exceeds budget ($${fee} > $${requirements.maxFee})`);
        }
        
        // Validity preference
        if (requirements.minValidityMonths) {
          if (product.valid_month >= requirements.minValidityMonths) {
            score += 3;
            reasons.push(`✓ Validity meets requirement (${product.valid_month} months)`);
          } else {
            score -= 3;
            reasons.push(`⚠ Validity below requirement (${product.valid_month} months)`);
          }
        }
        
        scoredProducts.push({
          product: product,
          score: score,
          reasons: reasons
        });
      });
      
      // Sort by score
      scoredProducts.sort((a, b) => b.score - a.score);
      
      // Display recommendations
      console.log('🏆 Recommendations (sorted by match score):\n');
      
      scoredProducts.forEach((item, index) => {
        const product = item.product;
        const medal = index === 0 ? '🥇' : index === 1 ? '🥈' : index === 2 ? '🥉' : '  ';
        
        console.log(`${medal} ${index + 1}. ${product.name_en}`);
        console.log(`   Match Score: ${item.score} points`);
        console.log(`   Code: ${product.card_product_code}`);
        console.log(`   Network: ${product.card_net_work}`);
        console.log(`   Currency: ${product.billing_currency}`);
        console.log(`   Type: ${product.share ? 'Shared Funds' : 'Dedicated Funds'}`);
        console.log(`   Fee: $${product.card_application_fee}`);
        console.log(`   Validity: ${product.valid_month} months`);
        
        if (item.reasons.length > 0) {
          console.log(`\n   Reasons:`);
          item.reasons.forEach(reason => {
            console.log(`     ${reason}`);
          });
        }
        
        console.log();
      });
      
      // Recommendation
      const topProduct = scoredProducts[0];
      if (topProduct.score > 0) {
        console.log('💡 Recommendation:');
        console.log(`   Use product code "${topProduct.product.card_product_code}" when creating your card`);
      } else {
        console.log('⚠️  No products fully match your requirements');
        console.log('   Consider adjusting your criteria or contact support');
      }
      
      return scoredProducts;
    } else {
      console.log('Failed to query products');
      return null;
    }
  } catch (error) {
    console.error('Error recommending products:', error.message);
    return null;
  }
}

// Example usage - Find best USD Shared Funds card with withdrawal support
const recommendations = await recommendCardProduct({
  currency: 'USD',
  shared: true,
  requireWithdrawal: true,
  maxFee: 5,
  minValidityMonths: 24,
  preferredNetwork: 'Mastercard'
});

Best Practices

• Query Before Card Creation: Always query available products before creating cards
• Cache Product Data: Product information changes infrequently - cache locally to reduce API calls
• Validate Product Codes: Ensure the product code exists before using it in card creation
• Consider All Factors: Evaluate network, currency, fees, and features when selecting products
• Update Cache Periodically: Refresh product cache daily or weekly
• Handle Errors Gracefully: Have fallback logic if product query fails

Understanding Card Product Fields

Card Network

• Visa: Widely accepted globally
• Mastercard: Excellent international acceptance
• DC (Diners Club): Premium network with specific merchant base

Card Type (share)

• Shared Funds Card (share: true): Sources from budget account, supports spending limits
• Dedicated Funds Card (share: false): Independent balance, no budget integration

Validity Period

• Specified in months from issuance date
• Common periods: 24 months (2 years), 36 months (3 years)
• Card expires at the end of the validity period

Application Fee

• One-time fee charged when creating a card
• Some products have zero fees
• Fees vary by product and card type

Withdrawal Support

• Determines if card balance can be withdrawn
• Important for dedicated funds cards
• May affect use cases (e.g., refund processing)

Related Endpoints

• Create a Card - Issue a new card using the product code
• Query All Cards - List all issued cards
• Query Card Details - View specific card information

Troubleshooting

No Products Returned

• Cause: Card issuance not enabled or no products configured
• Solution:
  • Contact your account manager to enable card issuance
  • Verify your account has card products assigned

Product Code Invalid When Creating Card

• Cause: Using an outdated or incorrect product code
• Solution:
  • Query products again to get current codes
  • Ensure you're copying the exact card_product_code
  • Check if the product is still available

Unexpected Product Features

• Cause: Product specifications may change over time
• Solution:
  • Always query products before card creation
  • Don't rely on hardcoded product codes
  • Refresh cached product data regularly

Security Considerations

• Access Control: Limit who can query product information
• Cache Security: Store cached product data securely
• Code Validation: Always validate product codes server-side
• Audit Logging: Log product queries for compliance

Interactive API Explorer