Skip to main content
The Platform Connector is an optional feature that integrates your VaultSaaS SDK deployment with the VaultSaaS platform for intelligent routing decisions and comprehensive transaction analytics.

​
Overview

When enabled via the platformApiKey configuration option, the connector provides:
  • Intelligent Routing: Remote routing decisions via POST /v1/routing/decide
  • Transaction Analytics: Batched transaction reporting to POST /v1/transactions/report
  • Webhook Forwarding: Batched webhook events to POST /v1/events/webhook
  • Graceful Fallback: Automatic fallback to local routing rules if platform is unavailable
The platform connector automatically falls back to local routing rules if the platform API is unreachable or times out, ensuring payment processing continuity.

​
Configuration

Enable the platform connector by providing a platformApiKey in your VaultClient configuration: 
import { VaultClient, StripeAdapter, DLocalAdapter } from '@vaultsaas/core';

const vault = new VaultClient({
  providers: {
    stripe: {
      adapter: StripeAdapter,
      config: {
        apiKey: process.env.STRIPE_API_KEY,
      },
    },
    dlocal: {
      adapter: DLocalAdapter,
      config: {
        xLogin: process.env.DLOCAL_X_LOGIN,
        xTransKey: process.env.DLOCAL_X_TRANS_KEY,
        secretKey: process.env.DLOCAL_SECRET_KEY,
      },
    },
  },
  routing: {
    rules: [{ match: { default: true }, provider: 'stripe' }],
  },
  platformApiKey: process.env.VAULTSAAS_PLATFORM_API_KEY,
  platform: {
    baseUrl: 'https://api.vaultsaas.com',
    timeoutMs: 100,
    batchSize: 100,
    flushIntervalMs: 2000,
    maxRetries: 2,
    initialBackoffMs: 100,
  },
});

​
Configuration Options

​
platformApiKey
string
required
API key to authenticate with the VaultSaaS platform. Setting this enables the connector.
​
platform.baseUrl
string
default:"https://api.vaultsaas.com"
Base URL for the VaultSaaS platform API.
​
platform.timeoutMs
number
default:75
Timeout in milliseconds for routing decision requests. Keep this low to preserve p95 payment latency.
​
platform.batchSize
number
default:50
Maximum number of items to include in a single batch for transaction reports and webhook events.
​
platform.flushIntervalMs
number
default:2000
Interval in milliseconds for periodic batch flushing.
​
platform.maxRetries
number
default:2
Maximum number of retry attempts for failed batch POST requests.
​
platform.initialBackoffMs
number
default:100
Initial backoff delay in milliseconds for retry logic. Uses exponential backoff.

​
How It Works

1

Routing Decision Request

When a payment is initiated, the connector sends a routing decision request to the platform:
// Platform routing request payload
interface PlatformRoutingRequest {
  currency: string;
  amount: number;
  paymentMethod: string;
  country?: string;
  cardBin?: string;
  metadata?: Record<string, string>;
}
The platform responds with a routing decision:
interface PlatformRoutingDecision {
  provider: string | null;
  source?: string;
  reason?: string;
  decisionId?: string;
  ttlMs?: number;
  cascade?: string[];
}
2

Fallback Handling

If the platform is unavailable or the request times out, the SDK automatically falls back to local routing rules configured in your VaultClient.
Keep timeoutMs low (default: 75ms) to ensure fast fallback and maintain low payment latency.
3

Transaction Reporting

After each transaction, the connector queues a transaction report that is batched and sent to the platform:
interface PlatformTransactionReport {
  id: string;
  provider: string;
  providerId?: string;
  status: string;
  amount: number;
  currency: string;
  country?: string;
  paymentMethod?: string;
  cardBin?: string;
  cardBrand?: string;
  latencyMs?: number;
  errorCategory?: string | null;
  routingSource?: 'local' | 'platform';
  routingDecisionId?: string;
  idempotencyKey?: string;
  timestamp: string;
}
4

Webhook Forwarding

Webhook events received from payment providers are batched and forwarded to the platform:
interface PlatformWebhookForwardEvent {
  id: string;
  type: string;
  provider: string;
  transactionId?: string;
  providerEventId: string;
  data: Record<string, unknown>;
  timestamp: string;
}

​
Batching and Flushing

The connector uses automatic batching to minimize network overhead:
  • Automatic Flush: Batches are sent immediately when they reach batchSize
  • Periodic Flush: Remaining items are flushed every flushIntervalMs
  • Manual Flush: Call vault.flush() to force immediate flush
// Manual flush before shutdown
await vault.flush();
vault.close();

​
Monitoring and Logging

The connector logs failures and degraded-mode operations to the configured logger: 
const vault = new VaultClient({
  // ... other config
  logging: {
    logger: console, // or your custom logger
  },
});
Use structured logging in production to capture platform connectivity issues and automatic fallback events.

​
Implementation Details

The connector is implemented in /home/daytona/workspace/source/src/platform/connector.ts:78 using:
  • BatchBuffer: Queue management for transaction and webhook batches (/home/daytona/workspace/source/src/platform/buffer.ts:1)
  • Retry Logic: Exponential backoff for failed requests (/home/daytona/workspace/source/src/platform/connector.ts:332)
  • Timeout Control: AbortController for request timeouts (/home/daytona/workspace/source/src/platform/connector.ts:278)

​
Best Practices

Low Timeout

Keep timeoutMs low (75-100ms) to preserve p95 payment latency during platform outages.

Local Fallback

Always configure local routing rules as fallback for platform unavailability.

Structured Logging

Use structured logs to monitor degraded-mode visibility and platform connectivity.

Graceful Shutdown

Call vault.flush() before shutdown to ensure pending batches are sent.

​
Example: Complete Setup

import { DLocalAdapter, StripeAdapter, VaultClient } from '@vaultsaas/core';

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

const vault = new VaultClient({
  providers: {
    stripe: {
      adapter: StripeAdapter,
      config: {
        apiKey: mustEnv('STRIPE_API_KEY'),
      },
    },
    dlocal: {
      adapter: DLocalAdapter,
      config: {
        xLogin: mustEnv('DLOCAL_X_LOGIN'),
        xTransKey: mustEnv('DLOCAL_X_TRANS_KEY'),
        secretKey: mustEnv('DLOCAL_SECRET_KEY'),
      },
    },
  },
  routing: {
    rules: [{ match: { default: true }, provider: 'stripe' }],
  },
  platformApiKey: mustEnv('VAULTSAAS_PLATFORM_API_KEY'),
  platform: {
    baseUrl: 'https://api.vaultsaas.com',
    timeoutMs: 100,
    batchSize: 100,
    flushIntervalMs: 2000,
    maxRetries: 2,
    initialBackoffMs: 100,
  },
  logging: {
    logger: console,
  },
});

const result = await vault.charge({
  amount: 1900,
  currency: 'USD',
  paymentMethod: {
    type: 'card',
    number: '4242424242424242',
    expMonth: 12,
    expYear: 2030,
    cvc: '123',
  },
  customer: {
    email: '[email protected]',
    address: {
      line1: '5 Main St',
      city: 'Austin',
      postalCode: '73301',
      country: 'US',
    },
  },
});

console.log(result.provider, result.routing.source, result.routing.reason);

// Graceful shutdown
await vault.flush();
vault.close();

Build docs developers (and LLMs) love

Get started for freeTalk to us