Card Management

Issue and manage virtual debit cards linked to your ClawPay vaults.

Overview

ClawPay cards are virtual Visa debit cards that:

• Draw funds from specific vaults

• Work at 40M+ merchants worldwide

• Support online and in-store purchases

• Enforce spending limits and merchant restrictions

• Provide real-time transaction notifications

Creating Cards

Basic Card

const card = await client.cards.create({
  vaultId: 'vault_123',
  cardholderName: 'John Doe',
  billingAddress: {
    line1: '123 Market St',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94103',
    country: 'US'
  }
});

console.log(`Card number: ${card.maskedNumber}`);
console.log(`CVV: ${card.cvv}`);
console.log(`Expires: ${card.expiryMonth}/${card.expiryYear}`);

Card with Spending Limits

const card = await client.cards.create({
  vaultId: 'vault_123',
  cardholderName: 'Alice Smith',
  spendingLimit: {
    daily: 1000,
    weekly: 5000,
    monthly: 20000,
    perTransaction: 500
  }
});

Card with Merchant Restrictions

const card = await client.cards.create({
  vaultId: 'vault_123',
  cardholderName: 'Bob Johnson',
  allowedCategories: [
    'cloud_services',
    'software',
    'advertising',
    'office_supplies'
  ],
  blockedMerchants: [
    'gambling',
    'adult_content',
    'cryptocurrency'
  ]
});

Card Properties

interface Card {
  id: string;
  vaultId: string;
  cardholderName: string;
  maskedNumber: string;      // 4242 •••• •••• 1234
  last4: string;              // 1234
  brand: 'visa' | 'mastercard';
  expiryMonth: number;        // 1-12
  expiryYear: number;         // 2027
  cvv: string;                // 123
  status: CardStatus;
  spendingLimit?: SpendingLimit;
  spent: {
    today: number;
    thisWeek: number;
    thisMonth: number;
  };
  createdAt: string;
}

type CardStatus = 'active' | 'frozen' | 'cancelled' | 'expired';

Revealing Card Details

For security, full card details are only returned during creation. To retrieve them later:

// Requires 2FA if enabled on your account
const details = await client.cards.reveal('card_123');

console.log(`Full number: ${details.number}`);
console.log(`CVV: ${details.cvv}`);
console.log(`Expires: ${details.expiryMonth}/${details.expiryYear}`);

Security Note: This endpoint requires authentication and may trigger 2FA. The response is not logged.

Spending Limits

Setting Limits

await client.cards.updateSpendingLimit('card_123', {
  daily: 2000,
  weekly: 10000,
  monthly: 40000,
  perTransaction: 1000
});

Checking Spent Amounts

const card = await client.cards.retrieve('card_123');

console.log(`Spent today: $${card.spent.today} / $${card.spendingLimit.daily}`);
console.log(`Spent this week: $${card.spent.thisWeek} / $${card.spendingLimit.weekly}`);
console.log(`Spent this month: $${card.spent.thisMonth} / $${card.spendingLimit.monthly}`);

const remainingToday = card.spendingLimit.daily - card.spent.today;
console.log(`Remaining today: $${remainingToday}`);

Temporary Limit Increases

// Increase limit for 24 hours
await client.cards.increaseLimit('card_123', {
  daily: 5000,
  duration: '24h',
  reason: 'Large equipment purchase'
});

Merchant Controls

Allowed Categories

Restrict card to specific merchant categories:

await client.cards.update('card_123', {
  allowedCategories: [
    'cloud_services',      // AWS, GCP, Azure
    'software',            // SaaS subscriptions
    'advertising',         // Google Ads, Meta Ads
    'office_supplies'      // Staples, Office Depot
  ]
});

Category Reference

Common MCC categories:

• cloud_services - Cloud hosting and infrastructure

• software - Software and SaaS

• advertising - Online advertising

• office_supplies - Office equipment and supplies

• travel - Airlines, hotels, car rentals

• restaurants - Dining and food services

• fuel - Gas stations

• telecommunications - Phone and internet services

Full category list →

Merchant Blocklist

await client.cards.update('card_123', {
  blockedMerchants: [
    'gambling',
    'adult_content',
    'cryptocurrency',
    'money_transfer'
  ]
});

Merchant Whitelist

Only allow specific merchants:

await client.cards.update('card_123', {
  whitelistOnly: true,
  allowedMerchants: [
    'amazon.com',
    'aws.amazon.com',
    'vercel.com',
    'stripe.com',
    'github.com'
  ]
});

Card Status Management

Freezing Cards

Temporarily disable a card:

await client.cards.freeze('card_123', {
  reason: 'Lost card',
  notifyCardholder: true
});

When frozen:

• All transactions are declined

• Card details remain valid

• Can be unfrozen at any time

Unfreezing Cards

await client.cards.unfreeze('card_123');

Cancelling Cards

Permanently disable a card:

await client.cards.cancel('card_123', {
  reason: 'Closing project',
  issueReplacement: false
});

Important: Cancellation is irreversible. Create a new card if needed.

Virtual Card Features

Single-Use Cards

Create a card for one-time use:

const card = await client.cards.create({
  vaultId: 'vault_123',
  cardholderName: 'John Doe',
  singleUse: true,
  spendingLimit: {
    perTransaction: 500
  }
});

The card is automatically cancelled after the first successful transaction.

Expiring Cards

Set custom expiration dates:

const card = await client.cards.create({
  vaultId: 'vault_123',
  cardholderName: 'Alice Smith',
  expiresAt: '2024-12-31', // ISO date
  autoCancel: true
});

Subscription Cards

Cards optimized for recurring payments:

const card = await client.cards.create({
  vaultId: 'vault_123',
  cardholderName: 'Bob Johnson',
  subscriptionMode: true,
  allowedMerchants: ['netflix.com', 'spotify.com'],
  spendingLimit: {
    monthly: 100
  }
});

Transaction Notifications

Real-Time Alerts

Receive instant notifications:

await client.cards.setNotifications('card_123', {
  email: ['[email protected]'],
  sms: ['[phone]'],
  webhook: true,
  events: [
    'transaction_approved',
    'transaction_declined',
    'daily_limit_reached',
    'suspicious_activity'
  ]
});

Webhook Events

app.post('/webhooks/clawpay', (req, res) => {
  const event = req.body;

  if (event.type === 'card.transaction_approved') {
    const txn = event.data.object;
    console.log(`${txn.merchant.name}: $${txn.amount}`);
  }

  if (event.type === 'card.declined') {
    const txn = event.data.object;
    console.log(`Declined: ${txn.declineReason}`);
  }

  res.sendStatus(200);
});

Card Security

3D Secure

Enable 3D Secure for online transactions:

await client.cards.update('card_123', {
  require3DSecure: true,
  phoneNumber: '[phone]' // For SMS verification
});

Geographic Restrictions

Limit card usage by region:

await client.cards.update('card_123', {
  allowedCountries: ['US', 'CA', 'GB'],
  blockedCountries: ['XX', 'YY'] // High-risk countries
});

Transaction Velocity Controls

Prevent rapid successive transactions:

await client.cards.setVelocityControls('card_123', {
  maxTransactionsPerHour: 5,
  maxTransactionsPerDay: 20,
  minTimeBetween: 60 // seconds
});

Card Metadata

Store custom data with cards:

await client.cards.update('card_123', {
  metadata: {
    employee_id: 'EMP-001',
    department: 'Engineering',
    project: 'Project Phoenix',
    manager: '[email protected]'
  }
});

// Retrieve card with metadata
const card = await client.cards.retrieve('card_123');
console.log(card.metadata.department); // 'Engineering'

Bulk Card Management

Issue Multiple Cards

const teamMembers = [
  { name: 'Alice Smith', limit: 1000 },
  { name: 'Bob Johnson', limit: 500 },
  { name: 'Carol White', limit: 750 }
];

const cards = await Promise.all(
  teamMembers.map(member =>
    client.cards.create({
      vaultId: 'vault_123',
      cardholderName: member.name,
      spendingLimit: { daily: member.limit }
    })
  )
);

console.log(`Issued ${cards.length} cards`);

Freeze All Cards

const cards = await client.cards.list({ vaultId: 'vault_123' });

await Promise.all(
  cards.data.map(card =>
    client.cards.freeze(card.id, {
      reason: 'Security review'
    })
  )
);

Transaction History

View card-specific transactions:

const transactions = await client.transactions.list({
  cardId: 'card_123',
  limit: 50,
  status: 'completed'
});

transactions.data.forEach(txn => {
  console.log(`${txn.merchant.name}: $${txn.amount}`);
});

Export Card Transactions

const csv = await client.cards.exportTransactions('card_123', {
  format: 'csv',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Card Analytics

Spending Insights

const analytics = await client.cards.getAnalytics('card_123', {
  period: '30d'
});

console.log(`Total spent: $${analytics.totalSpent}`);
console.log(`Transaction count: ${analytics.transactionCount}`);
console.log(`Average transaction: $${analytics.averageTransaction}`);
console.log(`Top merchants:`, analytics.topMerchants);
console.log(`Category breakdown:`, analytics.categoryBreakdown);

Decline Analysis

const declines = await client.cards.getDeclineAnalytics('card_123', {
  period: '30d'
});

console.log(`Total declines: ${declines.count}`);
console.log(`Decline reasons:`, declines.reasonBreakdown);
console.log(`Decline rate: ${declines.rate}%`);

Best Practices

1. Set Conservative Limits Initially

// Start conservative
const card = await client.cards.create({
  vaultId: 'vault_123',
  cardholderName: 'New Employee',
  spendingLimit: {
    daily: 100,
    monthly: 2000
  }
});

// Increase as trust builds
await client.cards.updateSpendingLimit(card.id, {
  daily: 500,
  monthly: 10000
});

2. Use Merchant Restrictions

// For developer tools card
await client.cards.create({
  vaultId: 'vault_123',
  cardholderName: 'Dev Team',
  allowedCategories: ['cloud_services', 'software'],
  allowedMerchants: [
    'aws.amazon.com',
    'vercel.com',
    'github.com',
    'openai.com'
  ]
});

3. Enable Notifications

await client.cards.setNotifications('card_123', {
  email: ['[email protected]'],
  events: [
    'transaction_approved',
    'transaction_declined',
    'daily_limit_reached'
  ]
});

4. Regular Audits

// Monthly card audit
async function auditCards(vaultId) {
  const cards = await client.cards.list({ vaultId });

  for (const card of cards.data) {
    const analytics = await client.cards.getAnalytics(card.id, {
      period: '30d'
    });

    if (analytics.transactionCount === 0) {
      console.log(`Inactive card: ${card.id}`);
      // Consider cancelling
    }

    if (analytics.declineRate > 10) {
      console.log(`High decline rate: ${card.id}`);
      // Investigate spending patterns
    }
  }
}

5. Freeze Lost Cards Immediately

// Endpoint for cardholders to freeze their own cards
app.post('/api/cards/freeze', async (req, res) => {
  const { cardId, userId } = req.body;

  // Verify ownership
  const card = await client.cards.retrieve(cardId);
  if (card.metadata.user_id !== userId) {
    return res.status(403).send('Unauthorized');
  }

  // Freeze immediately
  await client.cards.freeze(cardId, {
    reason: 'User-reported lost card',
    notifyCardholder: true
  });

  res.send({ success: true });
});

Troubleshooting

Card Declined

Common decline reasons:

const txn = await client.transactions.retrieve('txn_declined');

switch (txn.declineReason) {
  case 'insufficient_balance':
    console.log('Vault balance too low');
    break;
  case 'daily_limit_exceeded':
    console.log('Daily spending limit reached');
    break;
  case 'merchant_blocked':
    console.log('Merchant not allowed');
    break;
  case 'category_blocked':
    console.log('Merchant category not allowed');
    break;
  case 'card_frozen':
    console.log('Card is frozen');
    break;
}

Card Not Working

const card = await client.cards.retrieve('card_123');

if (card.status === 'frozen') {
  await client.cards.unfreeze(card.id);
}

if (card.status === 'cancelled') {
  console.log('Card is cancelled, issue a new one');
}

if (card.status === 'expired') {
  console.log('Card expired, issue replacement');
  await client.cards.issueReplacement(card.id);
}

Next Steps

• Vault Management

• Transaction Monitoring

• Authorization Rules

• API Reference