Required dependencies

npm install user@example.com

No native modules, no pod install, no Android linking required. For Node.js 18+ use the node entry points. For Cloudflare Workers or other edge runtimes, use the worker entry points which rely on the SubtleCryptoProvider and FetchHttpClient.

Project setup

1. Copy the source/ directory into your project, e.g. src/stripe-sdk/.
2. Ensure tsconfig.json targets ES2020 or later and has "moduleResolution": "bundler" or "node16"/"nodenext" since the source uses .js extensions in imports.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true
  }
}

3. Set your Stripe secret key as an environment variable:

export STRIPE_SECRET_KEY=sk_test_...

4. Instantiate the client pointing at the local source:

// src/stripeClient.ts
import Stripe from './stripe-sdk/stripe.cjs.node.js';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

5. For ESM projects, import from stripe.esm.node.ts instead and ensure "type": "module" is in package.json.

Public API

Stripe (default export)

import Stripe from './stripe-sdk/stripe.core.js';

const stripe = new Stripe(apiKey: string, config?: Stripe.StripeConfig);

The root client class. All API resources are exposed as properties (stripe.customers, stripe.checkout.sessions, stripe.billing.meters, etc.). Instantiate once and reuse. Accepts optional config for apiVersion, timeout, maxNetworkRetries, httpAgent, and more.

Checkout (namespace class)

import { Checkout } from './stripe-sdk/resources/Checkout/index.js';

// Exposed on the root client as:
stripe.checkout.sessions.create(params: Checkout.SessionCreateParams): Promise<Checkout.Session>
stripe.checkout.sessions.retrieve(id: string): Promise<Checkout.Session>
stripe.checkout.sessions.list(params: Checkout.SessionListParams): Promise<Stripe.ApiList<Checkout.Session>>
stripe.checkout.sessions.expire(id: string): Promise<Checkout.Session>

Use stripe.checkout.sessions to create and manage hosted payment pages. The namespace class groups all checkout sub-resources and delegates to SessionResource internally.

Billing (namespace class)

import { Billing } from './stripe-sdk/resources/Billing/index.js';

stripe.billing.alerts        // AlertResource
stripe.billing.creditGrants  // CreditGrantResource
stripe.billing.meters        // MeterResource
stripe.billing.meterEvents   // MeterEventResource
stripe.billing.meterEventAdjustments // MeterEventAdjustmentResource
stripe.billing.creditBalanceSummaries
stripe.billing.creditBalanceTransactions

Use stripe.billing to manage usage-based billing: define meters, emit metered events, issue credit grants, and configure threshold alerts.

Webhooks

import { Webhooks } from './stripe-sdk/Webhooks.js';

Webhooks.constructEvent(
  payload: string | Buffer,
  header: string,
  secret: string,
  tolerance?: number,
  cryptoProvider?: CryptoProvider
): Stripe.Event

Verifies a Stripe webhook signature and returns a parsed event object. Throws a StripeSignatureVerificationError if the signature is invalid or the timestamp is outside the tolerance window.

Working examples

Scenario - Create a Checkout Session

Accept a one-time payment using a hosted Stripe Checkout page.

import Stripe from './stripe-sdk/stripe.cjs.node.js';
import { Checkout } from './stripe-sdk/resources/Checkout/index.js';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

async function createCheckoutSession(): Promise<string | null> {
  const params: Checkout.SessionCreateParams = {
    mode: 'payment',
    line_items: [
      {
        price: 'price_1234567890',
        quantity: 1,
      },
    ],
    success_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel',
  };

  const session: Checkout.Session = await stripe.checkout.sessions.create(params);
  return session.url;
}

createCheckoutSession().then(url => console.log('Redirect to:', url));

Scenario - Verify an Incoming Webhook

Validate a Stripe webhook payload in an Express route before processing.

import express from 'express';
import Stripe from './stripe-sdk/stripe.cjs.node.js';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
const app = express();

app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['stripe-signature'] as string;
    let event: Stripe.Event;

    try {
      event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);
    } catch (err) {
      console.error('Webhook signature verification failed:', err);
      return res.status(400).send('Webhook Error');
    }

    if (event.type === 'checkout.session.completed') {
      const session = event.data.object as Stripe.Checkout.Session;
      console.log('Payment succeeded for session:', session.id);
    }

    res.json({ received: true });
  }
);

app.listen(3000);

Scenario - Create a Billing Meter and Emit Usage Events

Set up usage-based billing with meters and meter events.

import Stripe from './stripe-sdk/stripe.cjs.node.js';
import { Billing } from './stripe-sdk/resources/Billing/index.js';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

async function setupUsageBilling() {
  // Create a meter to track API calls
  const meter: Billing.Meter = await stripe.billing.meters.create({
    display_name: 'API Calls',
    event_name: 'api_call',
    default_aggregation: { formula: 'sum' },
  });
  console.log('Meter created:', meter.id);

  // Emit a usage event against that meter
  const meterEvent: Billing.MeterEvent = await stripe.billing.meterEvents.create({
    event_name: 'api_call',
    payload: {
      value: '1',
      stripe_customer_id: 'cus_ABC123',
    },
  });
  console.log('Meter event recorded:', meterEvent.identifier);
}

setupUsageBilling().catch(console.error);

Scenario - Create a Billing Portal Session

Redirect a customer to the Stripe-hosted billing portal to manage subscriptions.

import Stripe from './stripe-sdk/stripe.cjs.node.js';
import { BillingPortal } from './stripe-sdk/resources/BillingPortal/index.js';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

async function createPortalSession(customerId: string): Promise<string> {
  const params: BillingPortal.SessionCreateParams = {
    customer: customerId,
    return_url: 'https://example.com/account',
  };

  const session: BillingPortal.Session =
    await stripe.billingPortal.sessions.create(params);

  return session.url;
}

createPortalSession('cus_ABC123').then(url => console.log('Portal URL:', url));

File walkthrough

• stripe.core.ts — Defines the Stripe class; wires all resources as instance properties; reads config
• stripe.cjs.node.ts / stripe.esm.node.ts — Platform entry points for Node.js; attach NodeHttpClient and NodeCryptoProvider
• stripe.cjs.worker.ts / stripe.esm.worker.ts — Edge runtime entry points; use FetchHttpClient and SubtleCryptoProvider
• StripeResource.ts — Base class for all resource objects; provides _request() and related helpers
• RequestSender.ts — Builds raw HTTP requests, handles retry backoff, reads config from StripeContext
• StripeContext.ts — Immutable configuration container passed to all resources
• StripeEmitter.ts — Thin event emitter for request, response, and error lifecycle events
• Webhooks.ts — constructEvent() and signature verification; delegates hashing to CryptoProvider
• Error.ts — Typed error hierarchy: StripeError, StripeCardError, StripeInvalidRequestError, etc.
• Types.ts — Core TypeScript interfaces: RequestOptions, StripeConfig, paginator types
• autoPagination.ts — Wraps list responses with autoPagingEach() / autoPagingToArray() iteration
• multipart.ts — Encodes File and Buffer payloads for upload endpoints
• utils.ts — General purpose helpers: isObject, flatten, removeNullish, etc.
• shared.ts — Common request/response transform logic shared across resources
• lib.ts — SDK version and default apiVersion constants
• apiVersion.ts — Exports the current pinned API version string
• Decimal.ts — Arbitrary-precision decimal for financial arithmetic
• V2Coercion.ts — Coerces V2 API raw responses into typed objects
• ResourceNamespace.ts — Abstract base for namespace groupings; holds a Stripe reference
• resources.ts — Barrel that aggregates all resource and namespace classes for the root client
• crypto/CryptoProvider.ts — Abstract interface for hashing and HMAC
• crypto/NodeCryptoProvider.ts — Node.js crypto module implementation of CryptoProvider
• crypto/SubtleCryptoProvider.ts — Web SubtleCrypto implementation for edge runtimes
• net/HttpClient.ts — Abstract base HTTP client interface
• net/NodeHttpClient.ts — Node.js http/https implementation
• net/FetchHttpClient.ts — Fetch API implementation for workers/browsers
• platform/PlatformFunctions.ts — Abstract platform utilities (UUID, timing, etc.)
• platform/NodePlatformFunctions.ts — Node.js-specific platform implementations
• platform/WebPlatformFunctions.ts — Web/worker-compatible platform implementations
• resources/Apps/ — Apps namespace exposing secrets sub-resource for app secret storage
• resources/Billing/ — Billing namespace with meters, alerts, credit grants sub-resources
• resources/BillingPortal/ — BillingPortal namespace for customer self-service portal
• resources/Checkout/ — Checkout namespace for hosted payment sessions
• resources/Climate/ — Climate namespace for carbon removal orders and products

Common pitfalls and fixes

• ERR_UNKNOWN_FILE_EXTENSION or broken imports: The source uses .js extensions internally for ESM compatibility; set "moduleResolution": "NodeNext" or "Bundler" in tsconfig.json.
• Missing API key at build time: Instantiate Stripe lazily (inside a function) rather than at module load time, or supply a placeholder string like 'placeholder' for static analysis passes.
• Webhook raw body already parsed: Express json() middleware consumes the body stream; mount express.raw({ type: 'application/json' }) on the webhook route before any JSON body parser.
• Worker/edge runtime using Node.js imports: Import from stripe.esm.worker.ts (or use stripe/worker in the npm package) to avoid node:crypto and node:http references that are unavailable in edge environments.
• Auto-pagination hanging: autoPagingToArray requires a { limit: N } cap; omitting it will attempt to fetch all pages and may exhaust memory or hit rate limits.
• StripeSignatureVerificationError on valid events: Clock skew between your server and Stripe can exceed the default 300-second tolerance; synchronize server time via NTP or increase tolerance when calling constructEvent.

Vibe-coding prompt template

I have the Stripe Node.js SDK source (stripe@22.0.2) copied into `source/` in my project.
I also have a USAGE.md file at the root that explains all exports, file responsibilities, and working examples.

Please help me integrate this SDK into my existing Node.js/TypeScript project by doing the following step-by-step:

1. Read USAGE.md to understand the available exports and entry points.
2. Update my tsconfig.json to use "moduleResolution": "NodeNext" so the .js import extensions in source/ resolve correctly.
3. Create a `src/stripeClient.ts` that lazily instantiates Stripe using the source at `source/stripe.cjs.node.ts` and reads STRIPE_SECRET_KEY from environment variables.
4. Add an Express POST route at /webhook that reads the raw body and calls stripe.webhooks.constructEvent() using the real Webhooks export from source/Webhooks.ts.
5. Add a route to create a Checkout Session using the Checkout.SessionCreateParams type from source/resources/Checkout/index.ts.
6. Show me where to add error handling using the typed error classes from source/Error.ts.

Only use exports and symbols that appear in source/ and are documented in USAGE.md. Do not invent any API methods.

License and credit

The Stripe Node.js SDK is licensed under the MIT License. See source/ for any LICENSE file included with the source, or refer to the upstream repository. Upstream package: stripe on npm — maintained by Stripe, Inc..

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。

Courier Node.js SDK for Server-Side Notifications

Automation, Utilities & Developer Tools

免费