Troubleshooting

// Each adapter validates its credentials at construction time.
// Stripe requires `apiKey`:
const vault = new VaultClient({
  providers: {
    stripe: {
      adapter: StripeAdapter,
      config: {
        apiKey: process.env.STRIPE_API_KEY!, // must be non-empty
      },
    },
  },
  routing: {
    rules: [{ match: { default: true }, provider: 'stripe' }],
  },
});

// dLocal requires three credentials:
// config.xLogin, config.xTransKey, config.secretKey

// Paystack requires:
// config.secretKey

dlocal: {
  adapter: DLocalAdapter,
  config: {
    xLogin: process.env.DLOCAL_X_LOGIN!,
    xTransKey: process.env.DLOCAL_X_TRANS_KEY!,
    secretKey: process.env.DLOCAL_SECRET_KEY!,
    baseUrl: process.env.DLOCAL_BASE_URL, // 'https://sandbox.dlocal.com' for test
  },
},

stripe: {
  adapter: StripeAdapter,
  config: {
    apiKey: process.env.STRIPE_API_KEY!,
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!, // whsec_...
  },
},

config: {
  apiKey: process.env.STRIPE_API_KEY!,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
},

import express from 'express';
import { VaultClient, WebhookVerificationError } from '@vaultsaas/core';

const app = express();

// Capture raw body for webhook routes
app.use(
  '/webhooks',
  express.json({
    verify: (req, _res, buf) => {
      (req as any).rawBody = buf;
    },
  }),
);

app.post('/webhooks/stripe', async (req, res) => {
  try {
    const rawBody = (req as any).rawBody as Buffer;
    const headers = req.headers as Record<string, string>;
    const event = await vault.handleWebhook('stripe', rawBody, headers);
    console.log('Event:', event.type, event.providerEventId);
    res.sendStatus(200);
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return res.status(400).send(error.message);
    }
    res.sendStatus(500);
  }
});

routing: {
  rules: [
    // Specific rules first
    {
      provider: 'dlocal',
      match: { country: 'BR', paymentMethod: ['pix', 'boleto'] },
    },
    {
      provider: 'paystack',
      match: { currency: 'NGN' },
    },
    // Default fallback last (required)
    {
      provider: 'stripe',
      match: { default: true },
    },
  ],
},

routing: {
  rules: [
    // ... your specific rules ...
    { provider: 'stripe', match: { default: true } },
  ],
},

// Stripe supports: card, bank_transfer, wallet
// Stripe currencies: USD, EUR, GBP, CAD, AUD, JPY, etc.

// dLocal supports: card, pix, boleto, bank_transfer
// dLocal currencies: BRL, MXN, ARS, CLP, COP, PEN, UYU, etc.

// Paystack supports: card, bank_transfer, wallet
// Paystack currencies: NGN, GHS, ZAR, KES, USD

// This will throw ROUTING_PROVIDER_EXCLUDED:
await vault.charge({
  // ...
  routing: {
    provider: 'stripe',
    exclude: ['stripe'], // conflict
  },
});

// Fix: remove the exclusion or remove the override

// First call stores the result
await vault.charge({
  amount: 2500,
  currency: 'USD',
  paymentMethod: { type: 'card', token: 'tok_visa' },
  idempotencyKey: 'order-1001-v1',
});

// Same key, same payload -> returns cached result (OK)
await vault.charge({
  amount: 2500,
  currency: 'USD',
  paymentMethod: { type: 'card', token: 'tok_visa' },
  idempotencyKey: 'order-1001-v1',
});

// Same key, different amount -> throws IDEMPOTENCY_CONFLICT
await vault.charge({
  amount: 3000, // changed
  currency: 'USD',
  paymentMethod: { type: 'card', token: 'tok_visa' },
  idempotencyKey: 'order-1001-v1', // reused
});

// Fix: use a new key when the payload changes
await vault.charge({
  amount: 3000,
  currency: 'USD',
  paymentMethod: { type: 'card', token: 'tok_visa' },
  idempotencyKey: 'order-1001-v2', // new key
});

idempotency: {
  ttlMs: 7 * 24 * 60 * 60 * 1000, // 7 days
},

import type { IdempotencyRecord, IdempotencyStore } from '@vaultsaas/core';

class RedisIdempotencyStore implements IdempotencyStore {
  async get(key: string): Promise<IdempotencyRecord | null> { /* ... */ }
  async set(record: IdempotencyRecord): Promise<void> { /* ... */ }
  async delete(key: string): Promise<void> { /* ... */ }
  async clearExpired(): Promise<void> { /* ... */ }
}

platform: {
  timeoutMs: 150,    // low timeout for routing decisions
  batchSize: 100,    // report batch size
  flushIntervalMs: 2000,
  maxRetries: 2,
  initialBackoffMs: 100,
},

const result = await vault.charge(request);
if (result.routing.source === 'local') {
  console.warn('Charge was routed locally (platform may be unavailable)');
}

// Token-based card
const tokenCard: PaymentMethodInput = {
  type: 'card',
  token: 'pm_card_visa',
};

// Raw card details
const rawCard: PaymentMethodInput = {
  type: 'card',
  number: '4242424242424242',
  expMonth: 12,
  expYear: 2030,
  cvc: '123',
};

import type { VaultConfig } from '@vaultsaas/core';

const config: VaultConfig = {
  providers: {
    stripe: {
      adapter: StripeAdapter,       // required: constructor function
      config: {                     // required: plain object
        apiKey: 'sk_test_...',
      },
      // optional fields:
      // priority: 1,
      // enabled: true,
    },
  },
  // routing is optional but recommended:
  routing: {
    rules: [{ match: { default: true }, provider: 'stripe' }],
  },
};

// $25.00 USD = 2500 cents
await vault.charge({ amount: 2500, currency: 'USD', /* ... */ });

// 500 NGN = 50000 kobo
await vault.charge({ amount: 50000, currency: 'NGN', /* ... */ });

// 1000 JPY = 1000 (JPY is zero-decimal)
await vault.charge({ amount: 1000, currency: 'JPY', /* ... */ });

# Instead of ts-node
npx tsx quickstart.ts

node --version
# Must be v20.0.0 or higher

# If using nvm:
nvm install 20
nvm use 20

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

try {
  await vault.charge(request);
} catch (error) {
  if (error instanceof VaultError && error.code === 'CARD_DECLINED') {
    console.log('Decline code:', error.context.declineCode);
    console.log('Provider message:', error.context.providerMessage);
    // Show: "Your card was declined. Please try another payment method."
  }
}

const result = await vault.charge(request);

if (result.status === 'requires_action') {
  // The provider metadata may include a redirect URL or client secret
  // Use it to trigger 3DS on the frontend
  console.log('3DS required:', result.providerMetadata);
}

if (error instanceof VaultError && error.code === 'FRAUD_SUSPECTED') {
  // Do NOT retry -- flag for manual review
  await flagForFraudReview(request, error.context);
}

// Correct
await vault.charge({ amount: 2500, currency: 'USD', /* ... */ });

// Also correct (adapters normalize case internally)
await vault.charge({ amount: 2500, currency: 'usd', /* ... */ });

// Wrong -- not a valid ISO 4217 code
await vault.charge({ amount: 2500, currency: 'dollars', /* ... */ });

if (error instanceof VaultError && error.retriable) {
  // Queue for retry with exponential backoff
  await retryWithBackoff(() => vault.charge(request));
}

config: {
  apiKey: process.env.STRIPE_API_KEY!,
  timeoutMs: 30_000, // increase from default 15s
},