---
title: "Stripe SDK Setup"
description: "Configure the Stripe SDK for server and client-side usage, connecting to your Stripe account for payment processing."
canonical_url: "https://vercel.com/academy/subscription-store/stripe-sdk-setup"
md_url: "https://vercel.com/academy/subscription-store/stripe-sdk-setup.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-04-11T09:28:11.447Z"
content_type: "lesson"
course: "subscription-store"
course_title: "Launch a Subscription Store with Vercel and Stripe"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Stripe SDK Setup

# Stripe SDK Setup

Stripe provides official SDKs for both server and browser environments. The server SDK handles secure operations like creating checkout sessions, while the browser SDK redirects users to Stripe's hosted checkout page. This lesson sets up both.

## Outcome

Configure the Stripe SDK for both server and browser environments, ready to process subscriptions.

## Fast Track

1. Create a Stripe account at [stripe.com](https://stripe.com) and get API keys
2. Add `STRIPE_SECRET_KEY` and `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` to `.env.local`
3. Implement `utils/stripe/config.ts` and `utils/stripe/client.ts`

## Hands-on Exercise 2.1

Configure the Stripe SDK to work in your app:

**Requirements:**

1. Create a Stripe account and access test mode API keys
2. Add secret and publishable keys to environment variables
3. Create a server-side Stripe client with proper configuration
4. Create a browser-side Stripe loader for checkout redirects

**Implementation hints:**

- The server SDK uses your secret key (never expose this in the browser)
- The browser SDK uses your publishable key (safe to expose)
- Always use test mode during development
- Set the `apiVersion` to ensure consistent API behavior

## Try It

1. **Create Stripe account:**
   - Go to [stripe.com](https://stripe.com) and sign up
   - Navigate to [Developers → API keys](https://dashboard.stripe.com/test/apikeys)
   - You should see **Publishable key** and **Secret key** in test mode

2. **Add to environment:**
   ```bash title=".env.local"
   STRIPE_SECRET_KEY=sk_test_...
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
   ```

3. **Restart dev server:**
   ```bash
   pnpm dev
   ```

4. **Verify no errors:**
   The dev server should start without errors about missing Stripe configuration.

## Commit

```bash
git add -A
git commit -m "feat(billing): add Stripe SDK configuration"
```

## Done-When

- [ ] Stripe account created with test mode enabled
- [ ] `STRIPE_SECRET_KEY` added to `.env.local` (starts with `sk_test_`)
- [ ] `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` added to `.env.local` (starts with `pk_test_`)
- [ ] `utils/stripe/config.ts` exports initialized `stripe` client
- [ ] `utils/stripe/client.ts` exports `getStripe` function
- [ ] Dev server runs without Stripe-related errors

## Solution

### Step 1: Create Stripe Account

1. Visit [stripe.com](https://stripe.com) and sign up
2. Once in the dashboard, ensure you're in **Test mode** (toggle in the top right)
3. Navigate to **Developers → API keys**
4. Copy both keys:
   - **Publishable key** starts with `pk_test_`
   - **Secret key** starts with `sk_test_`

### Step 2: Configure Environment

Add the keys to your `.env.local`:

```bash title=".env.local"
# Existing Supabase vars
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGci...

# Add Stripe keys
STRIPE_SECRET_KEY=sk_test_abc123...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xyz789...
```

### Step 3: Create Server Stripe Client

Update `utils/stripe/config.ts`:

```typescript title="utils/stripe/config.ts"
import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? "", {
  apiVersion: "2025-02-24.acacia",
  appInfo: {
    name: "Foragers Guild",
    version: "1.0.0",
  },
});
```

This creates a Stripe client configured for server-side use:

- **`apiVersion`** - Locks to a specific API version for stability
- **`appInfo`** - Identifies your app in Stripe's dashboard and logs

### Step 4: Create Browser Stripe Loader

Update `utils/stripe/client.ts`:

```typescript title="utils/stripe/client.ts"
import { loadStripe, Stripe } from "@stripe/stripe-js";

let stripePromise: Promise<Stripe | null>;

export const getStripe = () => {
  if (!stripePromise) {
    stripePromise = loadStripe(
      process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY ?? ""
    );
  }
  return stripePromise;
};
```

This lazy-loads the Stripe.js library:

- **Singleton pattern** - Only loads once, reuses the same instance
- **`loadStripe`** - Async function from `@stripe/stripe-js`
- **Publishable key** - Safe to use in the browser

## File Structure After This Lesson

```
utils/
├── supabase/
│   ├── client.ts       ← From Section 1
│   ├── server.ts       ← From Section 1
│   └── proxy.ts        ← From Section 1
└── stripe/
    ├── config.ts       ← New: server Stripe client
    └── client.ts       ← New: browser Stripe loader
```

## Server vs Browser SDK

| SDK     | Package             | Key Type        | Use Case                                   |
| ------- | ------------------- | --------------- | ------------------------------------------ |
| Server  | `stripe`            | Secret key      | Create sessions, manage subscriptions      |
| Browser | `@stripe/stripe-js` | Publishable key | Redirect to checkout, collect card details |

The server SDK handles sensitive operations. The browser SDK handles client-side redirects.

## Test Mode vs Live Mode

| Mode | Key Prefix             | Behavior                         |
| ---- | ---------------------- | -------------------------------- |
| Test | `sk_test_`, `pk_test_` | No real charges, test cards work |
| Live | `sk_live_`, `pk_live_` | Real charges, real cards only    |

Always develop with test keys. Switch to live keys only for production deployment.

## Troubleshooting

**"Invalid API key" error:**

- Verify the secret key starts with `sk_test_`
- Check you copied the full key without extra spaces
- Ensure `.env.local` is at the project root

**"Stripe is not defined" in browser:**

- The browser SDK loads asynchronously
- Always `await getStripe()` before using
- Verify the publishable key is set

**API version warnings:**

- Different API versions have different response shapes
- Lock to a specific version to avoid breaking changes
- Update the version when you're ready to migrate


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)