Developers

Build with Vydapay

Everything you need to integrate corporate card issuing and expense management into your product. Clean APIs, comprehensive docs, and responsive support.

Get API Keys Read the Docs

99.99% API uptime

<50ms Average response time

50+ API endpoints

3 Official SDKs

Quick Start

Get started in 5 minutes

From zero to issuing cards in just a few steps.

Install the SDK

Install our official SDK for your language. We support Node.js, Python, and Ruby with full TypeScript definitions.

# Using npm
npm install @vydapay/sdk

# Using yarn
yarn add @vydapay/sdk

# Using pnpm
pnpm add @vydapay/sdk

# Using pip
pip install vydapay

# Using poetry
poetry add vydapay

# Using pipenv
pipenv install vydapay

# Using bundler (add to Gemfile)
gem 'vydapay'

# Then run
bundle install

# Or install directly
gem install vydapay

Authenticate with your API key

Get your API keys from the dashboard. Use test keys (sk_test_) for development.

const Vydapay = require('@vydapay/sdk');

// Initialize with your secret key
const vydapay = new Vydapay('sk_test_abc123...');

// Or use environment variables (recommended)
const vydapay = new Vydapay(process.env.VYDAPAY_SECRET_KEY);

// TypeScript support included
import Vydapay from '@vydapay/sdk';
const vydapay: Vydapay = new Vydapay(process.env.VYDAPAY_SECRET_KEY!);

import vydapay
import os

# Set API key directly
vydapay.api_key = 'sk_test_abc123...'

# Or use environment variables (recommended)
vydapay.api_key = os.environ.get('VYDAPAY_SECRET_KEY')

# You can also pass it per-request
card = vydapay.Card.create(
    api_key='sk_test_abc123...',
    type='virtual',
    ...
)

require 'vydapay'

# Configure with your API key
Vydapay.api_key = 'sk_test_abc123...'

# Or use environment variables (recommended)
Vydapay.api_key = ENV['VYDAPAY_SECRET_KEY']

# In Rails, put this in config/initializers/vydapay.rb
Vydapay.configure do |config|
  config.api_key = Rails.application.credentials.vydapay_secret_key
end

Create a cardholder

Before issuing cards, create a cardholder representing the person who will use the card.

const cardholder = await vydapay.cardholders.create({
  email: 'sarah.mitchell@acme.com',
  name: {
    first_name: 'Sarah',
    last_name: 'Mitchell'
  },
  phone: '+447700900123',
  billing_address: {
    line1: '123 Business Street',
    line2: 'Floor 4',
    city: 'London',
    postal_code: 'EC1A 1BB',
    country: 'GB'
  },
  metadata: {
    employee_id: 'EMP-4521',
    department: 'Engineering',
    manager: 'john.smith@acme.com'
  }
});

console.log('Created cardholder:', cardholder.id);
// Created cardholder: ch_abc123def456

cardholder = vydapay.Cardholder.create(
    email='sarah.mitchell@acme.com',
    name={
        'first_name': 'Sarah',
        'last_name': 'Mitchell'
    },
    phone='+447700900123',
    billing_address={
        'line1': '123 Business Street',
        'line2': 'Floor 4',
        'city': 'London',
        'postal_code': 'EC1A 1BB',
        'country': 'GB'
    },
    metadata={
        'employee_id': 'EMP-4521',
        'department': 'Engineering',
        'manager': 'john.smith@acme.com'
    }
)

print(f'Created cardholder: {cardholder.id}')
# Created cardholder: ch_abc123def456

cardholder = Vydapay::Cardholder.create(
  email: 'sarah.mitchell@acme.com',
  name: {
    first_name: 'Sarah',
    last_name: 'Mitchell'
  },
  phone: '+447700900123',
  billing_address: {
    line1: '123 Business Street',
    line2: 'Floor 4',
    city: 'London',
    postal_code: 'EC1A 1BB',
    country: 'GB'
  },
  metadata: {
    employee_id: 'EMP-4521',
    department: 'Engineering',
    manager: 'john.smith@acme.com'
  }
)

puts "Created cardholder: #{cardholder.id}"
# Created cardholder: ch_abc123def456

Issue a virtual card

Create a virtual card with spending limits and controls. Cards are issued instantly.

const card = await vydapay.cards.create({
  type: 'virtual',
  currency: 'GBP',
  cardholder_id: cardholder.id,
  
  // Set a monthly spending limit of £500
  spending_limit: {
    amount: 50000, // Amount in pence
    interval: 'monthly'
  },
  
  // Configure spending controls
  spending_controls: {
    allowed_categories: [
      'software_services',
      'office_supplies',
      'advertising'
    ],
    blocked_categories: [
      'gambling',
      'adult_entertainment'
    ],
    allowed_countries: ['GB', 'IE', 'US']
  },
  
  metadata: {
    purpose: 'Software subscriptions',
    budget_code: 'ENG-2025-Q1'
  }
});

console.log('Card created!');
console.log('Card ID:', card.id);
console.log('Last 4:', card.last_four);
console.log('Status:', card.status);

// Card created!
// Card ID: card_xyz789def456
// Last 4: 4821
// Status: active

card = vydapay.Card.create(
    type='virtual',
    currency='GBP',
    cardholder_id=cardholder.id,
    
    # Set a monthly spending limit of £500
    spending_limit={
        'amount': 50000,  # Amount in pence
        'interval': 'monthly'
    },
    
    # Configure spending controls
    spending_controls={
        'allowed_categories': [
            'software_services',
            'office_supplies',
            'advertising'
        ],
        'blocked_categories': [
            'gambling',
            'adult_entertainment'
        ],
        'allowed_countries': ['GB', 'IE', 'US']
    },
    
    metadata={
        'purpose': 'Software subscriptions',
        'budget_code': 'ENG-2025-Q1'
    }
)

print('Card created!')
print(f'Card ID: {card.id}')
print(f'Last 4: {card.last_four}')
print(f'Status: {card.status}')

card = Vydapay::Card.create(
  type: 'virtual',
  currency: 'GBP',
  cardholder_id: cardholder.id,
  
  # Set a monthly spending limit of £500
  spending_limit: {
    amount: 50000,  # Amount in pence
    interval: 'monthly'
  },
  
  # Configure spending controls
  spending_controls: {
    allowed_categories: [
      'software_services',
      'office_supplies',
      'advertising'
    ],
    blocked_categories: [
      'gambling',
      'adult_entertainment'
    ],
    allowed_countries: ['GB', 'IE', 'US']
  },
  
  metadata: {
    purpose: 'Software subscriptions',
    budget_code: 'ENG-2025-Q1'
  }
)

puts 'Card created!'
puts "Card ID: #{card.id}"
puts "Last 4: #{card.last_four}"
puts "Status: #{card.status}"

Set up webhooks

Receive real-time notifications when transactions occur, cards are frozen, or limits are reached.

// 1. Create a webhook endpoint
const webhook = await vydapay.webhooks.create({
  url: 'https://your-app.com/webhooks/vydapay',
  events: [
    'transaction.created',
    'transaction.declined',
    'card.frozen',
    'spending_limit.reached'
  ]
});

console.log('Webhook secret:', webhook.secret);
// Store this secret securely!

// 2. Handle webhooks in your app (Express.js example)
const express = require('express');
const app = express();

app.post('/webhooks/vydapay', 
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-vydapay-signature'];
    
    let event;
    try {
      event = vydapay.webhooks.constructEvent(
        req.body,
        signature,
        process.env.WEBHOOK_SECRET
      );
    } catch (err) {
      console.log('Webhook signature verification failed');
      return res.status(400).send(`Webhook Error: \${err.message}`);
    }

    // Handle the event
    switch (event.type) {
      case 'transaction.created':
        const transaction = event.data.object;
        console.log(`New transaction: £\${transaction.amount / 100}`);
        // Send notification, update your database, etc.
        break;
        
      case 'transaction.declined':
        const declined = event.data.object;
        console.log(`Declined: \${declined.decline_reason}`);
        // Alert the cardholder
        break;
        
      case 'spending_limit.reached':
        console.log('Spending limit reached!');
        // Notify finance team
        break;
    }

    res.json({ received: true });
  }
);

# 1. Create a webhook endpoint
webhook = vydapay.Webhook.create(
    url='https://your-app.com/webhooks/vydapay',
    events=[
        'transaction.created',
        'transaction.declined',
        'card.frozen',
        'spending_limit.reached'
    ]
)

print(f'Webhook secret: {webhook.secret}')
# Store this secret securely!

# 2. Handle webhooks in your app (Flask example)
from flask import Flask, request, jsonify
import os

app = Flask(__name__)

@app.route('/webhooks/vydapay', methods=['POST'])
def handle_webhook():
    payload = request.data
    signature = request.headers.get('X-Vydapay-Signature')
    
    try:
        event = vydapay.Webhook.construct_event(
            payload,
            signature,
            os.environ.get('WEBHOOK_SECRET')
        )
    except ValueError as e:
        return jsonify(error=str(e)), 400
    
    # Handle the event
    if event.type == 'transaction.created':
        transaction = event.data.object
        print(f'New transaction: £{transaction.amount / 100}')
        
    elif event.type == 'transaction.declined':
        declined = event.data.object
        print(f'Declined: {declined.decline_reason}')
        
    elif event.type == 'spending_limit.reached':
        print('Spending limit reached!')
    
    return jsonify(received=True)

Common Patterns

Code examples for common tasks

Freeze a card instantly

Immediately disable a card when suspicious activity is detected.

// Freeze the card
const card = await vydapay.cards.freeze('card_xyz789');
console.log(card.status); // 'frozen'

// Unfreeze when resolved
await vydapay.cards.unfreeze('card_xyz789');

Update spending limit

Increase or decrease limits in real-time as needs change.

const card = await vydapay.cards.update('card_xyz789', {
  spending_limit: {
    amount: 100000, // £1,000
    interval: 'monthly'
  }
});

Get transaction history

Retrieve transactions with filters for reporting and analysis.

const transactions = await vydapay.transactions.list({
  card_id: 'card_xyz789',
  created_after: '2025-01-01T00:00:00Z',
  status: 'completed',
  limit: 100
});

const total = transactions.data.reduce(
  (sum, t) => sum + t.amount, 0
);
console.log(`Total spend: £\${total / 100}`);

Attach receipt to transaction

Upload receipts programmatically for automatic matching.

const fs = require('fs');

const receipt = await vydapay.transactions.attachReceipt(
  'txn_abc123',
  { file: fs.createReadStream('./receipt.pdf') }
);

console.log(receipt.status); // 'matched'

Create single-use card

Issue a card that automatically cancels after one transaction.

const card = await vydapay.cards.create({
  type: 'virtual',
  currency: 'GBP',
  cardholder_id: 'ch_abc123',
  spending_limit: {
    amount: 15000, // £150 max
    interval: 'all_time'
  },
  single_use: true // Cancels after first use
});

Lock card to specific merchant

Create a card that only works at a specific vendor.

const card = await vydapay.cards.create({
  type: 'virtual',
  currency: 'GBP',
  cardholder_id: 'ch_abc123',
  spending_controls: {
    allowed_merchants: ['mid_github_inc']
  },
  metadata: { vendor: 'GitHub' }
});