> ## Documentation Index
> Fetch the complete documentation index at: https://dhiwisepvtltd-5e04e6a4.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Payments

> Step-by-step tutorial for adding Stripe payments to a Rocket.new Build app: checkout sessions, webhooks, subscriptions, and testing card flows safely.

Stripe is the fastest way to accept payments in your Rocket app. This tutorial walks you through connecting Stripe, creating a pricing page, setting up checkout, handling webhooks, and testing the full payment flow.

> [!NOTE]
>
> You'll need a [Stripe account](https://stripe.com) to follow this tutorial. Free to create - no charges until you process real payments.

## What you'll set up

By the end of this tutorial, your app will have:

* A pricing page with plan options
* A Stripe Checkout flow for processing payments
* Webhook handling for payment events (successful charges, subscription changes)
* Test mode verification before going live

## Connect Stripe

**1. Get your Stripe API keys**

Log into your [Stripe Dashboard](https://dashboard.stripe.com/apikeys) and copy your **publishable key** and **secret key**. Make sure you're in **test mode** (toggle in the top-right of the Stripe dashboard).

You'll have two pairs of keys:

* **Test keys** - for development and testing (start with `pk_test_` and `sk_test_`)
* **Live keys** - for real payments (start with `pk_live_` and `sk_live_`)

**2. Add keys to your Rocket app**

Ask Rocket to set up Stripe integration with your keys:

```plaintext wrap theme={null}
Set up Stripe integration. My publishable key is pk_test_xxxxx and my secret key is sk_test_xxxxx. Store the secret key as a server-side environment variable.
```

Rocket will store your secret key securely as an environment variable and configure the Stripe SDK in your app.

> [!WARNING]
>
> Never paste your **live** secret key directly into a prompt. Use test keys during development. Add live keys through Rocket's environment variable settings when you're ready to go live.

**3. Create products in Stripe**

In your Stripe Dashboard, go to **Products** and create the plans you want to offer. For example:

* **Free** - \$0/month
* **Pro** - \$29/month
* **Enterprise** - \$99/month

Copy the **price ID** for each plan (starts with `price_`). You'll reference these when building your pricing page.

## Build a pricing page

Ask Rocket to create a pricing page that displays your plans and links to Stripe Checkout.

```plaintext wrap theme={null}
Create a pricing page with three plans: Free ($0/month), Pro ($29/month), and Enterprise ($99/month). The Pro plan should be highlighted as "Most Popular." Each plan should list 4-5 features and have a "Get Started" button that initiates Stripe Checkout for the corresponding plan. Use price IDs: price_free_xxx, price_pro_xxx, price_enterprise_xxx.
```

Rocket will generate a responsive pricing page with plan cards, feature lists, and checkout buttons.

## Set up Stripe Checkout

Stripe Checkout is a hosted payment page that handles card input, validation, and compliance for you. Ask Rocket to wire up the checkout flow:

```plaintext wrap theme={null}
Create a server-side API route that creates a Stripe Checkout session. When a user clicks a pricing plan's "Get Started" button, redirect them to Stripe Checkout for that plan. After successful payment, redirect to a /success page. After cancellation, redirect back to the pricing page.
```

The checkout flow works like this:

1. User clicks a plan on your pricing page
2. Your app creates a Stripe Checkout session on the server
3. User is redirected to Stripe's hosted payment page
4. After payment, user returns to your success page

> [!NOTE]
>
> Stripe Checkout handles PCI compliance, card validation, 3D Secure, and local payment methods automatically. You don't need to build a custom payment form.

## Handle webhooks

Webhooks let Stripe notify your app when payment events happen - a charge succeeds, a subscription renews, or a payment fails.

**1. Create a webhook endpoint**

Ask Rocket to add a webhook handler:

```plaintext wrap theme={null}
Create a webhook endpoint at /api/webhooks/stripe that handles these Stripe events: checkout.session.completed (activate the user's subscription), invoice.payment_succeeded (renew access), and customer.subscription.deleted (revoke access). Verify the webhook signature using the Stripe webhook secret.
```

**2. Get your webhook secret**

In the Stripe Dashboard, go to **Developers → Webhooks** and add an endpoint pointing to your app's webhook URL. Stripe will give you a **webhook signing secret** (starts with `whsec_`).

Add this secret as an environment variable in your Rocket app.

**3. Configure events**

Select the events you want Stripe to send to your webhook:

* `checkout.session.completed` - a customer completed payment
* `invoice.payment_succeeded` - a subscription renewed
* `invoice.payment_failed` - a payment attempt failed
* `customer.subscription.deleted` - a subscription was canceled

## Test your payment flow

Before going live, test everything end-to-end in Stripe's test mode.

**1. Use test card numbers**

Stripe provides test card numbers for different scenarios:

| Card number | Scenario |
| - | - |
| `4242 4242 4242 4242` | Successful payment |
| `4000 0000 0000 3220` | Requires 3D Secure authentication |
| `4000 0000 0000 9995` | Payment declined |

Use any future expiration date, any 3-digit CVC, and any billing zip code.

**2. Test the full flow**

Walk through the complete payment path:

1. Go to your pricing page
2. Click a plan's checkout button
3. Complete payment with a test card
4. Verify you land on the success page
5. Check the Stripe Dashboard to confirm the payment appears

**3. Test webhooks locally**

Use the [Stripe CLI](https://stripe.com/docs/stripe-cli) to forward webhook events to your staging environment for testing:

```plaintext wrap theme={null}
stripe listen --forward-to localhost:3000/api/webhooks/stripe
```

Trigger a test event and verify your webhook handler processes it correctly.

**4. Go live**

When everything works in test mode:

1. Switch your Stripe Dashboard to **live mode**
2. Replace test API keys with live keys in Rocket's environment variables
3. Update your webhook endpoint to use the live webhook secret
4. Click **Launch** to deploy your app to production

> [!WARNING]
>
> Double-check that your live secret key is stored as a server-side environment variable, not exposed in client-side code. Run the [security checklist](https://dhiwisepvtltd-5e04e6a4.mintlify.site/learn/tutorials/security-checklist.md) before accepting real payments.

## What's next?

> **[Security checklist](https://dhiwisepvtltd-5e04e6a4.mintlify.site/learn/tutorials/security-checklist.md)**
>
> Ensure API keys and payment flows are locked down.

> **[Launch your site](https://dhiwisepvtltd-5e04e6a4.mintlify.site/build/launch-web/launch-your-site.md)**
>
> Test payment flows in staging before going live.

> **[Deploy to the web](https://dhiwisepvtltd-5e04e6a4.mintlify.site/build/launch-web/launch-your-site.md)**
>
> Launch your app with payments to a live URL.

> **[Prompting for Build](https://dhiwisepvtltd-5e04e6a4.mintlify.site/learn/guides/for-build.md)**
>
> Write better prompts for app features and integrations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.