Stripe API keys and the Node.js SDK

This chapter follows What is Stripe?.

Stripe authenticates API requests with API keys. Treat them like passwords: leak a secret key and someone can move money or refund charges in your account. The Node.js SDK wraps Stripe’s REST API with typed helpers, automatic retries for network blips, and webhook signature verification.

Publishable, secret, and restricted keys

Live keys use pk_live_, sk_live_, and rk_live_. The Dashboard Developers → API keys page lists keys for the active mode or sandbox.

Never commit keys to git. Load them from the environment—see Env vars, process and globals in NodeJS.

Loading keys in Node.js

Use two variables in development:

1
STRIPE_SECRET_KEY=sk_test_...
2
STRIPE_PUBLISHABLE_KEY=pk_test_...

Your Express app reads the secret key at startup. Templates or a small /config.js endpoint can expose the publishable key to the browser for Stripe.js—never send the secret key to the client.

Installing the stripe package and creating a client

Install the current major SDK (for example stripe@23 on npm) alongside Express:

1
npm install stripe express

Create one shared module that constructs a Stripe client instance. Do not use the deprecated pattern of setting a global API key on the module.

1
import Stripe from 'stripe';
2

3
if (!process.env.STRIPE_SECRET_KEY) {
4
  throw new Error('Missing STRIPE_SECRET_KEY');
5
}
6

7
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
8
  apiVersion: '2026-09-30.endive',
9
});

Import stripe from that file in route handlers. Pinning apiVersion keeps behavior stable when Stripe ships new API versions; upgrade deliberately after reading the changelog.

A minimal health route proves the key format without charging money:

1
import { stripe } from '../stripe-client.js';
2

3
export async function getBalance(_req, res) {
4
  const balance = await stripe.balance.retrieve();
5
  res.json({ available: balance.available });
6
}

API version and idempotency

Every response includes the API version Stripe used. Your client’s apiVersion parameter requests a specific version on each call.

Idempotency keys let you safely retry POST requests without creating duplicate objects. Pass a unique key per logical operation (often your internal order id):

1
import { stripe } from '../stripe-client.js';
2

3
export async function createCustomer(req, res) {
4
  const customer = await stripe.customers.create(
5
    { email: req.body.email, metadata: { appUserId: req.body.userId } },
6
    { idempotencyKey: `customer-${req.body.userId}` },
7
  );
8
  res.json({ customerId: customer.id });
9
}

Stripe stores idempotency results for about 24 hours. Reuse the same key with a different body returns an error.

Errors and retries

Failed calls throw Stripe.errors.StripeError subclasses. Branch on error.type:

The SDK retries idempotent GETs and some network failures automatically. For POSTs you initiate, combine idempotency keys with your own retry policy.

Rotating keys safely

Rotation limits blast radius if a key leaks:

1. Create a new restricted key in the Dashboard with the same permissions.
2. Deploy the new key to your secrets store and restart servers.
3. Monitor traffic; disable the old key once nothing uses it.

For publishable keys, update front-end config and CDN caches after rotation. Webhook signing secrets are separate from API keys; rotate them in the webhook endpoint settings and update STRIPE_WEBHOOK_SECRET before disabling the old secret.

Next: Customers in Stripe.