Skip to main content

​
Overview

The StripeAdapter implements the PaymentAdapter interface to process payments through Stripe’s API. It supports cards, bank transfers, and digital wallets across 40+ countries and 20+ currencies.

​
Class Signature

class StripeAdapter implements PaymentAdapter {
  readonly name = 'stripe';
  static readonly supportedMethods = ['card', 'bank_transfer', 'wallet'] as const;
  static readonly supportedCurrencies = [
    'USD', 'EUR', 'GBP', 'CAD', 'AUD', 'JPY', 'CHF', 'SEK', 'NOK', 'DKK',
    'NZD', 'SGD', 'HKD', 'MXN', 'BRL', 'PLN', 'CZK', 'HUF', 'RON', 'BGN',
    'INR', 'MYR', 'THB'
  ] as const;
  static readonly supportedCountries = [
    'US', 'GB', 'DE', 'FR', 'CA', 'AU', 'JP', 'IT', 'ES', 'NL', 'BE', 'AT',
    'CH', 'SE', 'NO', 'DK', 'FI', 'IE', 'PT', 'LU', 'NZ', 'SG', 'HK', 'MY',
    'MX', 'BR', 'PL', 'CZ', 'HU', 'RO', 'BG', 'HR', 'CY', 'EE', 'GR', 'LV',
    'LT', 'MT', 'SK', 'SI', 'IN', 'TH'
  ] as const;
  readonly metadata: AdapterMetadata;
  
  constructor(config: Record<string, unknown>);
}

​
Constructor

new StripeAdapter(config: Record<string, unknown>)

​
Configuration

​
apiKey
string
required
Stripe secret API key (starts with sk_test_ or sk_live_).Required. Throws VaultConfigError if not provided.
​
webhookSecret
string
Stripe webhook signing secret for signature verification (starts with whsec_).Optional. Required if using handleWebhook() method.
​
baseUrl
string
Custom Stripe API base URL.Default: "https://api.stripe.com"
​
timeoutMs
number
Request timeout in milliseconds.Default: 15000 (15 seconds)
​
fetchFn
typeof fetch
Custom fetch implementation for testing or special network requirements.Default: global fetch

​
Configuration Example

import { StripeAdapter } from '@vaultsaas/core';

const stripe = new StripeAdapter({
  apiKey: process.env.STRIPE_SECRET_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
  timeoutMs: 20000,
});

​
Supported Capabilities

​
Payment Methods

​
card
Payment Method
Credit and debit cards via Stripe’s card processing network.Supports tokenized cards and raw card details (PCI-compliant environments only).
​
bank_transfer
Payment Method
Bank transfers using Stripe’s customer balance API.Available in select markets with ACH, SEPA, and other local bank transfer methods.
​
wallet
Payment Method
Digital wallets including Apple Pay, Google Pay, and other Stripe-supported wallets.Requires wallet-specific integration and tokenization.

​
Supported Currencies

23 currencies including:
  • Americas: USD, CAD, MXN, BRL
  • Europe: EUR, GBP, CHF, SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN
  • Asia-Pacific: JPY, AUD, NZD, SGD, HKD, INR, MYR, THB

​
Supported Countries

42 countries across:
  • North America (US, CA)
  • Europe (EU27 + UK, Switzerland, Norway)
  • Asia-Pacific (JP, AU, NZ, SG, HK, MY, IN, TH)
  • Latin America (MX, BR)

​
Methods

Implements all PaymentAdapter interface methods:
  • charge() - Creates a Stripe Payment Intent with automatic capture
  • authorize() - Creates a Payment Intent with manual capture
  • capture() - Captures an authorized Payment Intent
  • refund() - Creates a Stripe Refund
  • void() - Cancels an uncaptured Payment Intent
  • getStatus() - Retrieves Payment Intent status
  • listPaymentMethods() - Returns available Stripe payment methods
  • handleWebhook() - Verifies and processes Stripe webhook events

​
Webhook Events

The adapter maps Stripe webhook events to VaultSaaS event types:
Stripe EventVaultSaaS Event
payment_intent.succeededpayment.completed
payment_intent.payment_failedpayment.failed
payment_intent.processingpayment.pending
payment_intent.requires_actionpayment.requires_action
charge.refundedpayment.refunded
charge.dispute.createdpayment.disputed
charge.dispute.closedpayment.dispute_resolved
payout.paidpayout.completed
payout.failedpayout.failed

​
Webhook Verification

Stripe webhooks are verified using HMAC-SHA256 signatures with timestamp validation:
  • Signature header: stripe-signature
  • Timestamp tolerance: 5 minutes
  • Signature format: t={timestamp},v1={signature}
await stripe.handleWebhook(
  request.body,
  request.headers
);
Webhook verification requires webhookSecret to be configured in the adapter constructor. Without it, handleWebhook() will throw a WebhookVerificationError.

​
Status Mapping

Stripe Payment Intent statuses are mapped to VaultSaaS statuses:
Stripe StatusVaultSaaS Status
succeededcompleted
requires_captureauthorized
requires_actionrequires_action
processingpending
canceledcancelled
requires_payment_methoddeclined
requires_confirmationpending
Otherfailed

​
Error Handling

The adapter enriches errors with Stripe-specific context: 
{
  code: 'PROVIDER_ERROR',
  hint: {
    providerCode: 'card_declined',
    providerMessage: 'Your card was declined.',
    declineCode: 'insufficient_funds',
    raw: { /* original Stripe error */ }
  },
  operation: 'charge'
}

​
Provider Metadata

Payment results include Stripe-specific metadata: 
{
  providerMetadata: {
    stripeStatus: 'succeeded',
    paymentMethod: 'pm_1234567890'
  }
}

​
Usage Example

import { StripeAdapter } from '@vaultsaas/core';

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

// Direct charge
const result = await stripe.charge({
  amount: 5000, // $50.00 in cents
  currency: 'USD',
  paymentMethod: {
    type: 'card',
    token: 'pm_1234567890',
  },
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
  },
  description: 'Order #12345',
});

console.log(result.status); // 'completed'
console.log(result.providerId); // 'ch_3Abc123...'

Build docs developers (and LLMs) love

Get started for freeTalk to us