Nuda Kit

Billing

Stripe Configuration

Setting up Stripe for payments.

Nuda Kit uses Stripe for payment processing. This guide walks you through setting up Stripe for both development and production.

Overview

Stripe integration includes:

Checkout Sessions

Hosted checkout pages for secure payments.

Customer Portal

Self-service subscription management.

Webhooks

Real-time payment event notifications.

Subscriptions

Recurring billing with automatic renewals.

Getting Your Stripe API Key

Step 1: Create a Stripe Account

  1. Go to stripe.com
  2. Click Start now or Sign in
  3. Complete the registration process

Step 2: Access the Dashboard

  1. Log in to your Stripe Dashboard
  2. You'll start in Test mode (toggle in the top-right)

Step 3: Get Your Secret Key

  1. Click Developers in the left sidebar
  2. Click API keys
  3. Under Standard keys, find your Secret key
  4. Click Reveal test key to see it
  5. Copy the key (starts with sk_test_ for test mode)
Never commit your secret key to version control! Always use environment variables.

Step 4: Add to Environment

Add the key to your backend/.env file:

STRIPE_SECRET_KEY=sk_test_your_secret_key_here

Environment Variables

VariableDescriptionExample
STRIPE_SECRET_KEYYour Stripe secret keysk_test_xxx or sk_live_xxx
STRIPE_WEBHOOK_SECRETWebhook signing secretwhsec_xxx
STRIPE_API_VERSIONStripe API version2025-10-29.clover
STRIPE_DEVICE_NAMEDevice name for Stripe CLIlocalhost
STRIPE_EVENTS_WHITELISTWebhook events to handleSee below

Events Whitelist

STRIPE_EVENTS_WHITELIST=checkout.session.completed,invoice.paid,invoice.payment_failed,customer.subscription.created,customer.subscription.updated,customer.subscription.deleted

Webhook Configuration

Webhooks notify your app when payment events occur (e.g., successful checkout, subscription canceled).

Local Development (Docker)

Nuda Kit includes a Stripe CLI Docker container that automatically forwards webhooks to your backend. No manual installation required!

1. Start Docker Services

docker compose up -d

2. Get the Webhook Secret

View the Stripe container logs to find your webhook signing secret:

docker compose logs stripe

Look for a line like:

> Ready! Your webhook signing secret is whsec_xxxxx

3. Add to Environment

Copy the secret and add it to your backend/.env:

STRIPE_WEBHOOK_SECRET=whsec_xxxxx
The webhook secret changes each time the container restarts. Update your .env if you restart Docker.

Production Webhooks

  1. Go to Stripe Dashboard → Webhooks
  2. Click Add endpoint
  3. Enter your webhook URL: 
    https://your-api-domain.com/webhooks/stripe
  4. Select events to listen for:
    • checkout.session.completed
    • invoice.paid
    • invoice.payment_failed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
  5. Click Add endpoint
  6. Copy the Signing secret and add to production environment

Webhook Events

EventWhen It FiresHandler
checkout.session.completedPayment successfulCreates subscription
invoice.paidInvoice payment receivedUpdates subscription
invoice.payment_failedPayment failedHandle failure
customer.subscription.createdNew subscriptionSync subscription
customer.subscription.updatedSubscription changedUpdate status
customer.subscription.deletedSubscription canceledMark as canceled

Test Mode vs Live Mode

ModeKey PrefixUse Case
Testsk_test_Development & testing
Livesk_live_Production payments

Switching Modes

Toggle between Test and Live mode in the Stripe Dashboard (top-right corner). Each mode has separate:

  • API keys
  • Products and prices
  • Customers
  • Webhook endpoints
Always develop and test with Test mode. Only use Live mode for production.

Test Cards

Use these card numbers in Test mode:

Card NumberDescription
4242 4242 4242 4242Successful payment
4000 0000 0000 32203D Secure authentication
4000 0000 0000 9995Payment declined
4000 0000 0000 0341Card error

Use any future expiration date and any 3-digit CVC.

What's Included

Backend

  • StripeService — Complete Stripe API wrapper
  • Webhook Controller — Handles all payment events
  • Subscription Management — Create, update, cancel
  • Customer Management — Automatic customer creation
  • Signature verification for security

Frontend

  • Billing Settings Page — Subscription management UI
  • Plan Cards — Display pricing options
  • Checkout Integration — Redirect to Stripe Checkout
  • Portal Integration — Link to Customer Portal

Configuration Checklist

  • Create Stripe account
  • Get API keys from Dashboard
  • Add STRIPE_SECRET_KEY to .env
  • Start Docker (docker compose up -d)
  • Get webhook secret from Stripe CLI container logs
  • Add STRIPE_WEBHOOK_SECRET to .env
  • Create products and prices in Stripe
  • Add plans to database (see Plans & Products)
  • Test with test cards

Troubleshooting

IssueSolution
"STRIPE_SECRET_KEY is not set"Add key to .env file
"Webhook signature verification failed"Check STRIPE_WEBHOOK_SECRET matches container logs
Webhooks not received locallyEnsure Stripe CLI container is running (docker compose ps)
Webhook secret changedGet new secret from docker compose logs stripe
Subscription not createdVerify webhook events are firing

Resources

Magic Links

Allow users to log in with a secure email link instead of a password.

Plans & Products

Managing subscription plans.