0
# Stripe Node.js Library
1

2
The official Stripe Node.js library provides comprehensive access to Stripe's REST API with full TypeScript support. This library handles payments, subscriptions, customer management, and all other Stripe functionality through a well-organized, namespaced API structure.
3

4
## Package Information
5

6
- **Package Name**: stripe
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install stripe`
10

11
## Core Imports
12

13
```typescript
14
import Stripe from 'stripe';
15
```
16

17
For named import:
18

19
```typescript
20
import { Stripe } from 'stripe';
21
```
22

23
For CommonJS:
24

25
```javascript
26
const Stripe = require('stripe');
27
```
28

29
## Basic Usage
30

31
```typescript
32
import Stripe from 'stripe';
33

34
const stripe = new Stripe('sk_test_...', {
35
  apiVersion: '2025-08-27.basil',
36
  typescript: true
37
});
38
```
39

40
## Core Concepts
41

42
### Configuration
43

44
```typescript { .api }
45
interface StripeConfig {
46
  apiVersion?: '2025-08-27.basil';          // Latest API version
47
  typescript?: true;                        // Enable TypeScript support
48
  maxNetworkRetries?: number;              // Default: 1, max retries for failed requests
49
  httpAgent?: HttpAgent;                   // Custom HTTP agent for proxy usage
50
  httpClient?: HttpClient;                 // Custom HTTP client implementation
51
  timeout?: number;                        // Request timeout in ms (default: 80000)
52
  host?: string;                          // API host override
53
  port?: string | number;                 // API port override
54
  protocol?: 'http' | 'https';           // Protocol override
55
  telemetry?: boolean;                    // Enable/disable telemetry (default: true)
56
  appInfo?: AppInfo;                      // Plugin identification
57
  stripeAccount?: string;                 // Connect account for all requests
58
  stripeContext?: string;                 // Context for all requests
59
}
60

61
const stripe = new Stripe(apiKey, {
62
  apiVersion: '2025-08-27.basil',
63
  typescript: true,
64
  maxNetworkRetries: 3,
65
  timeout: 30000
66
});
67
```
68

69
### Request Options
70

71
```typescript { .api }
72
interface RequestOptions {
73
  apiKey?: string;                        // Override API key per request
74
  idempotencyKey?: string;               // Idempotency key for safe retries
75
  stripeAccount?: string;                // Connect account per request
76
  stripeContext?: string;                // Context per request  
77
  apiVersion?: string;                   // API version per request
78
  maxNetworkRetries?: number;            // Retry limit per request
79
  timeout?: number;                      // Timeout per request
80
  host?: string;                         // Host per request
81
}
82
```
83

84
## Architecture
85

86
The Stripe Node.js library is organized into namespaces and resources:
87

88
- **Core Resources**: Direct API resources accessible via `stripe.resourceName`
89
- **Namespaced Resources**: Organized by functional area via `stripe.namespace.resource`
90
- **Special Features**: Webhooks, OAuth, test helpers, and V2 API resources
91

92
### Standard Resource Methods
93

94
```typescript { .api }
95
// Most resources follow standard CRUD patterns:
96
interface StandardResource<T> {
97
  create(params: CreateParams, options?: RequestOptions): Promise<T>;
98
  retrieve(id: string, options?: RequestOptions): Promise<T>;
99
  update(id: string, params: UpdateParams, options?: RequestOptions): Promise<T>;
100
  list(params?: ListParams, options?: RequestOptions): Promise<ApiList<T>>;
101
  del?(id: string, options?: RequestOptions): Promise<DeletedResource>;
102
}
103

104
// Example usage
105
const customer = await stripe.customers.create({
106
  email: 'customer@example.com',
107
  name: 'John Doe'
108
});
109

110
const paymentIntent = await stripe.paymentIntents.create({
111
  amount: 2000,
112
  currency: 'usd',
113
  customer: customer.id
114
}, {
115
  idempotencyKey: 'unique-key-123'
116
});
117
```
118

119
## Major Functional Areas
120

121
### [Core Resources](./core-resources.md)
122

123
Essential payment processing and customer management resources:
124

125
```typescript { .api }
126
// Payment processing
127
const paymentIntent = await stripe.paymentIntents.create({
128
  amount: 2000,
129
  currency: 'usd',
130
  payment_method: 'pm_card_visa',
131
  confirm: true
132
});
133

134
// Customer management
135
const customer = await stripe.customers.create({
136
  email: 'customer@example.com',
137
  payment_method: 'pm_card_visa'
138
});
139

140
// Charges and refunds
141
const charge = await stripe.charges.create({
142
  amount: 2000,
143
  currency: 'usd',
144
  source: 'tok_visa'
145
});
146
```
147

148
### [Subscriptions](./subscriptions.md)
149

150
Complete subscription lifecycle management:
151

152
```typescript { .api }
153
// Create subscription
154
const subscription = await stripe.subscriptions.create({
155
  customer: 'cus_123',
156
  items: [{
157
    price: 'price_123',
158
    quantity: 1
159
  }],
160
  payment_behavior: 'default_incomplete',
161
  expand: ['latest_invoice.payment_intent']
162
});
163

164
// Manage subscription items
165
const subscriptionItem = await stripe.subscriptionItems.create({
166
  subscription: subscription.id,
167
  price: 'price_456'
168
});
169
```
170

171
### [Billing](./billing.md)
172

173
Advanced billing features including usage metering and credit management:
174

175
```typescript { .api }
176
// Usage metering
177
const meterEvent = await stripe.billing.meterEvents.create({
178
  event_name: 'api_request',
179
  payload: {
180
    stripe_customer_id: 'cus_123',
181
    value: '1'
182
  }
183
});
184

185
// Credit grants
186
const creditGrant = await stripe.billing.creditGrants.create({
187
  customer: 'cus_123',
188
  amount: {
189
    monetary: {
190
      value: 1000,
191
      currency: 'usd'
192
    }
193
  }
194
});
195
```
196

197
### [Issuing](./issuing.md)
198

199
Card issuing and transaction management:
200

201
```typescript { .api }
202
// Create cardholder
203
const cardholder = await stripe.issuing.cardholders.create({
204
  name: 'John Doe',
205
  email: 'john.doe@example.com',
206
  phone_number: '+15551234567',
207
  type: 'individual'
208
});
209

210
// Issue card
211
const card = await stripe.issuing.cards.create({
212
  cardholder: cardholder.id,
213
  currency: 'usd',
214
  type: 'virtual'
215
});
216
```
217

218
### [Treasury](./treasury.md)
219

220
Financial account management and money movement:
221

222
```typescript { .api }
223
// Create financial account
224
const financialAccount = await stripe.treasury.financialAccounts.create({
225
  supported_currencies: ['usd'],
226
  features: {
227
    card_issuing: { requested: true },
228
    deposit_insurance: { requested: true }
229
  }
230
});
231

232
// Create outbound transfer
233
const transfer = await stripe.treasury.outboundTransfers.create({
234
  financial_account: financialAccount.id,
235
  destination_payment_method: 'pm_123',
236
  amount: 10000,
237
  currency: 'usd'
238
});
239
```
240

241
### [Terminal](./terminal.md)
242

243
In-person payment processing:
244

245
```typescript { .api }
246
// Create reader
247
const reader = await stripe.terminal.readers.create({
248
  registration_code: 'simulated-wpe',
249
  label: 'Blue Rabbit',
250
  location: 'tml_loc_123'
251
});
252

253
// Process payment
254
const paymentIntent = await stripe.terminal.readers.processPaymentIntent(
255
  reader.id,
256
  {
257
    payment_intent: 'pi_123'
258
  }
259
);
260
```
261

262
### [Webhooks](./webhooks.md)
263

264
Event handling and webhook management:
265

266
```typescript { .api }
267
// Verify webhook signature
268
const event = stripe.webhooks.constructEvent(
269
  payload,
270
  signature,
271
  endpointSecret
272
);
273

274
// Handle events
275
switch (event.type) {
276
  case 'payment_intent.succeeded':
277
    const paymentIntent = event.data.object;
278
    console.log('Payment succeeded:', paymentIntent.id);
279
    break;
280
  default:
281
    console.log('Unhandled event type:', event.type);
282
}
283
```
284

285
### [Checkout](./checkout.md)
286

287
Hosted payment pages and complete checkout flows:
288

289
```typescript { .api }
290
// Create checkout session
291
const session = await stripe.checkout.sessions.create({
292
  mode: 'payment',
293
  line_items: [
294
    {
295
      price: 'price_123',
296
      quantity: 1
297
    }
298
  ],
299
  success_url: 'https://example.com/success',
300
  cancel_url: 'https://example.com/cancel'
301
});
302
```
303

304
### [Tax](./tax.md)
305

306
Comprehensive tax calculation and compliance:
307

308
```typescript { .api }
309
// Calculate tax
310
const calculation = await stripe.tax.calculations.create({
311
  currency: 'usd',
312
  line_items: [
313
    {
314
      amount: 1000,
315
      reference: 'item_1'
316
    }
317
  ],
318
  customer_details: {
319
    address: {
320
      country: 'US',
321
      state: 'CA',
322
      postal_code: '94105'
323
    },
324
    address_source: 'billing'
325
  }
326
});
327
```
328

329
### [Identity](./identity.md)
330

331
Identity verification and KYC compliance:
332

333
```typescript { .api }
334
// Create verification session
335
const verification = await stripe.identity.verificationSessions.create({
336
  type: 'document',
337
  options: {
338
    document: {
339
      allowed_types: ['passport', 'driving_license'],
340
      require_matching_selfie: true
341
    }
342
  },
343
  return_url: 'https://example.com/verify/return'
344
});
345
```
346

347
### [Radar](./radar.md)
348

349
Advanced fraud prevention and risk management:
350

351
```typescript { .api }
352
// Create value list for fraud prevention
353
const blocklist = await stripe.radar.valueLists.create({
354
  alias: 'blocked_emails',
355
  name: 'Blocked Email Domains',
356
  item_type: 'email'
357
});
358

359
// Add item to blocklist
360
await stripe.radar.valueListItems.create({
361
  value_list: blocklist.id,
362
  value: 'suspicious@example.com'
363
});
364
```
365

366
### [Configuration](./configuration.md)
367

368
Advanced configuration options, error handling, and authentication:
369

370
```typescript { .api }
371
// Error handling
372
try {
373
  const payment = await stripe.paymentIntents.create(params);
374
} catch (err) {
375
  if (err instanceof stripe.errors.StripeCardError) {
376
    console.log('Card error:', err.decline_code);
377
  } else if (err instanceof stripe.errors.StripeInvalidRequestError) {
378
    console.log('Invalid parameters:', err.param);
379
  }
380
}
381
```
382

383
## Quick Start Example
384

385
```typescript { .api }
386
import Stripe from 'stripe';
387

388
const stripe = new Stripe('sk_test_...', {
389
  apiVersion: '2025-08-27.basil',
390
  typescript: true
391
});
392

393
// Complete payment flow
394
async function processPayment() {
395
  try {
396
    // Create customer
397
    const customer = await stripe.customers.create({
398
      email: 'customer@example.com'
399
    });
400

401
    // Create payment intent
402
    const paymentIntent = await stripe.paymentIntents.create({
403
      amount: 2000,
404
      currency: 'usd',
405
      customer: customer.id,
406
      payment_method_types: ['card']
407
    });
408

409
    // Confirm payment (in real scenario, this happens on frontend)
410
    const confirmedPayment = await stripe.paymentIntents.confirm(
411
      paymentIntent.id,
412
      {
413
        payment_method: 'pm_card_visa'
414
      }
415
    );
416

417
    console.log('Payment successful:', confirmedPayment.status);
418
    return confirmedPayment;
419
  } catch (error) {
420
    console.error('Payment failed:', error);
421
    throw error;
422
  }
423
}
424
```
425

426
## Response Types and Pagination
427

428
```typescript { .api }
429
// API List with auto-pagination
430
interface ApiList<T> {
431
  object: 'list';
432
  data: Array<T>;
433
  has_more: boolean;
434
  url: string;
435
}
436

437
// Auto-pagination methods
438
const customers = stripe.customers.list({ limit: 10 });
439

440
// Iterate through all customers
441
for await (const customer of customers) {
442
  console.log(customer.email);
443
}
444

445
// Convert to array with limit
446
const customerArray = await customers.autoPagingToArray({ limit: 100 });
447

448
// Process each item with callback
449
await customers.autoPagingEach(async (customer) => {
450
  await processCustomer(customer);
451
});
452
```
453

454
## Event Monitoring
455

456
```typescript { .api }
457
// Monitor requests and responses
458
stripe.on('request', (event) => {
459
  console.log('Request:', {
460
    method: event.method,
461
    url: event.url,
462
    requestId: event.request_id
463
  });
464
});
465

466
stripe.on('response', (event) => {
467
  console.log('Response:', {
468
    status: event.status_code,
469
    requestId: event.request_id,
470
    elapsed: event.elapsed
471
  });
472
});
473
```
474

475
This library provides access to 127+ API resources across multiple namespaces, with comprehensive TypeScript support and extensive error handling capabilities. Key capabilities include payment processing, subscription management, hosted checkout, tax calculation, identity verification, fraud prevention, card issuing, treasury management, terminal payments, and advanced webhooks. Each functional area has specialized methods beyond the standard CRUD operations to support domain-specific workflows.