Skip to main content
VaultSaaS SDK normalizes provider adapters behind a single orchestration client, providing a unified interface for payment processing across multiple payment providers.

​
Architecture Diagram

​
Core Components

​
VaultClient

The main orchestration client that serves as the entry point for all operations:
  • Charge: Process one-time payments
  • Authorize: Pre-authorize payments for later capture
  • Capture: Capture previously authorized payments
  • Refund: Process refunds for completed payments
  • Void: Cancel authorized payments
  • Status: Check transaction status
  • Webhooks: Handle and normalize provider webhook events
The VaultClient is located at src/client/vault-client.ts:65 and manages all provider adapters, routing logic, and platform integration.

​
Router

Evaluates routing rules and provider capabilities to determine which payment provider should handle each transaction. 
import { Router } from '@vaultsaas/core';

const router = new Router(
  [
    {
      provider: 'stripe',
      match: {
        currency: 'USD',
        paymentMethod: 'card',
      },
    },
    {
      provider: 'dlocal',
      match: { default: true },
    },
  ],
  {
    adapterMetadata: metadataRecord,
    logger: customLogger,
  }
);
The Router must include at least one rule with match.default: true to serve as a fallback.

​
Provider Adapters

Implement provider-specific API calls and webhook verification. Each adapter:
  • Translates normalized requests into provider-specific API calls
  • Normalizes provider responses into canonical formats
  • Handles webhook signature verification
  • Declares supported payment methods, currencies, and countries
import { StripeAdapter } from '@vaultsaas/core';

const adapter = new StripeAdapter({
  apiKey: process.env.STRIPE_API_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
});

​
Error Mapper

Normalizes provider-specific and network failures into canonical VaultError codes with consistent error shapes.
Error Mapping
import { mapProviderError } from '@vaultsaas/core';

try {
  await adapter.charge(request);
} catch (error) {
  throw mapProviderError(error, {
    provider: 'stripe',
    operation: 'charge',
  });
}
All errors include code, category, suggestion, docsUrl, retriable, and context fields for comprehensive error handling.

​
Idempotency Store

Prevents duplicate operation execution for repeated idempotency keys.
Idempotency Configuration
import { MemoryIdempotencyStore } from '@vaultsaas/core';

const vault = new VaultClient({
  // ... provider config
  idempotency: {
    store: new MemoryIdempotencyStore(),
    ttlMs: 24 * 60 * 60 * 1000, // 24 hours
  },
});
The default MemoryIdempotencyStore is not suitable for production multi-instance deployments. Implement a distributed store using Redis or your database.

​
Platform Connector

Optional component for telemetry and remote routing integration with VaultSaaS platform.
Platform Integration
const vault = new VaultClient({
  providers: { /* ... */ },
  routing: { /* ... */ },
  platformApiKey: process.env.VAULTSAAS_API_KEY,
  platform: {
    baseUrl: 'https://api.vaultsaas.com',
    timeoutMs: 5000,
    batchSize: 100,
    flushIntervalMs: 10000,
  },
});
When enabled, the Platform Connector sends transaction reports and webhook events for analytics, and can provide dynamic routing decisions.

​
Data Flow

​
Payment Processing Flow

  1. Application calls vault.charge(request)
  2. VaultClient validates configuration
  3. Router evaluates rules and selects provider
  4. Idempotency check (if idempotencyKey provided)
  5. Provider adapter executes API call
  6. Error mapper handles failures
  7. Response normalized and returned
  8. Transaction report queued to Platform Connector

​
Webhook Processing Flow

  1. Provider sends webhook to application endpoint
  2. Application calls vault.handleWebhook(provider, payload, headers)
  3. Adapter verifies signature (if supported)
  4. Event normalized to VaultEvent format
  5. Event returned to application
  6. Event queued to Platform Connector

​
Configuration Validation

The VaultClient validates configuration at initialization:
src/client/vault-client.ts:76
validateVaultConfig(config);
Configuration validation ensures:
  • At least one enabled provider exists
  • All adapters are properly configured
  • Routing rules include a default fallback
  • Required credentials are present

​
Next Steps

Routing

Learn how to configure routing rules

Error Handling

Understand error types and handling

Idempotency

Implement safe retry logic

Webhooks

Handle provider webhooks

Build docs developers (and LLMs) love

Get started for freeTalk to us