Skip to main content
Get your first payment running in under 10 minutes with the VaultSaaS SDK.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 20+ (or Bun 1.1+) installed
  • A Stripe test secret key (sk_test_...)
Always use test API keys during development. Never commit API keys to version control.

​
Installation

1

Install the SDK

Install the @vaultsaas/core package using your preferred package manager:
npm install @vaultsaas/core
2

Create your quickstart file

Create a new file called quickstart.ts in your project directory:
quickstart.ts
import { StripeAdapter, VaultClient, VaultError } from '@vaultsaas/core';

function mustEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing required env var: ${name}`);
  }
  return value;
}

const vault = new VaultClient({
  providers: {
    stripe: {
      adapter: StripeAdapter,
      config: {
        apiKey: mustEnv('STRIPE_API_KEY'),
      },
    },
  },
  routing: {
    rules: [{ match: { default: true }, provider: 'stripe' }],
  },
});

try {
  const result = await vault.charge({
    amount: 2500,
    currency: 'USD',
    paymentMethod: {
      type: 'card',
      number: '4242424242424242',
      expMonth: 12,
      expYear: 2030,
      cvc: '123',
    },
    customer: {
      email: 'buyer@example.com',
      name: 'Taylor Buyer',
      address: {
        line1: '510 Townsend St',
        city: 'San Francisco',
        postalCode: '94103',
        country: 'US',
      },
    },
    metadata: {
      orderId: 'ord_demo_1001',
      source: 'quickstart',
    },
    idempotencyKey: 'charge-ord_demo_1001-v1',
  });

  console.log('Payment created:', {
    id: result.id,
    status: result.status,
    provider: result.provider,
  });
} catch (error) {
  if (error instanceof VaultError) {
    console.error('VaultError', {
      code: error.code,
      category: error.category,
      suggestion: error.suggestion,
      docsUrl: error.docsUrl,
      context: error.context,
    });
    process.exit(1);
  }

  throw error;
}
This example uses Stripe’s test card number 4242424242424242 which always succeeds. See Stripe’s testing guide for more test cards.
3

Run the quickstart

Execute the file with your Stripe test API key:
STRIPE_API_KEY=sk_test_xxx bun quickstart.ts
You should see output similar to:
{
  "id": "ch_3AbC123...",
  "status": "succeeded",
  "provider": "stripe"
}

​
Understanding the code

Let’s break down what’s happening in the quickstart:
  1. Initialize VaultClient: Configure the SDK with your payment provider (Stripe) and routing rules
  2. Create a charge: Call vault.charge() with payment details, customer information, and metadata
  3. Handle errors: Catch and handle VaultError instances with detailed error information
The idempotencyKey ensures that if you run the same charge request multiple times, it won’t create duplicate payments. Learn more in the Idempotency guide.

​
Next steps

Now that you’ve created your first payment, explore these concepts to build production-ready integrations:

Routing

Learn how to intelligently route payments across multiple providers

Idempotency

Prevent duplicate charges and ensure safe retries

Error Handling

Handle payment errors gracefully with detailed error context

Webhooks

Process real-time payment events from providers

Build docs developers (and LLMs) love

Get started for freeTalk to us