Skip to main content

Stripe

JetShip is pre-configured to support Stripe as the default payment provider, allowing you to easily integrate payments in your Next.js application. This guide will walk you through the steps to configure Stripe and begin accepting payments.

⚙️ Configuration​

Before starting the integration, you'll need to create a Stripe account and obtain the necessary credentials.

Step-by-Step Guide to Configure Stripe​

  1. Create a Stripe Account

    • If you haven't already, sign up for a Stripe account at stripe.com

  2. Log in to Stripe Dashboard

  3. Select Test Mode or Live Mode

    • Toggle between Test Mode (for development) and Live Mode (for production)
    • The toggle switch is in the top right corner of the Stripe dashboard
    • Always test thoroughly in Test Mode before switching to Live Mode

  4. Obtain API Keys

    • Navigate to Developers > API keys in the dashboard
    • Copy the Publishable Key: 
      NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
    • Reveal and copy the Secret Key: 
      STRIPE_SECRET_KEY=sk_test_...

  5. Set Up Webhooks

    You have two options for setting up webhooks in your local development environment:

    ngrok is a globally distributed reverse proxy platform that makes your localhost accessible to the internet. It's perfect for testing webhooks and sharing your local development environment with teammates.

    1. Install ngrok

      npm install ngrok -g

    2. Add ngrok Commands

      In your root package.json:

      {
        "scripts": {
          "ngrok": "ngrok http 3000"
        }
      }

      In apps/web/package.json:

      {
        "scripts": {
          "ngrok": "ngrok http 3000"
        }
      }

    3. Start ngrok

      npm run ngrok

      This will give you a public URL like https://xxxx-xx-xx-xxx-xx.ngrok.io

    4. Configure Stripe Webhook

      • Go to Developers > Webhooks in the Stripe dashboard
      • Click Add endpoint
      • Enter your ngrok URL + webhook path: 
        https://xxxx-xx-xx-xxx-xx.ngrok.io/api/webhooks/stripe
      • Select these events:
        • checkout.session.completed
        • customer.subscription.updated
      • Click Add endpoint
      • Copy the Signing Secret to your .env file: 
        STRIPE_WEBHOOK_SECRET=whsec_...

    The Stripe CLI provides a simpler way to test webhooks during local development.

    1. Install Stripe CLI

    2. Login to Stripe CLI

      stripe login

    3. Forward Events to Your Local Server

      stripe listen --forward-to localhost:3000/api/webhooks/stripe

    4. Trigger Test Events

      • Open a new terminal window (keep the webhook listener running)

      • Use the stripe trigger command to simulate webhook events:

        # Test subscription events
        stripe trigger customer.subscription.created
        stripe trigger customer.subscription.updated

        # Test checkout completion
        stripe trigger checkout.session.completed

      • The events will be forwarded to your local server

      • Check your terminal with the webhook listener for the response

    5. Copy Webhook Secret

      • The CLI will display a webhook signing secret
      • Add it to your .env file: 
        STRIPE_WEBHOOK_SECRET=whsec_...

Environment Variables​

Add these variables to your .env file:

# Stripe API Keys
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

🛍️ Creating Products in Stripe​

Step 1: Create Products​

  1. Go to Products in your Stripe dashboard
  2. Click Add product
  3. Fill in the product details:
    • Name (e.g., "Pro Plan")
    • Description
    • Images (optional)
    • Pricing information

Step 2: Set Up Pricing​

For each product, you can create multiple prices:

  1. One-time Prices

    {
      paymentType: "one-off",
      lineItems: [{
        priceId: "price_xxxxx",    // Copy this ID from Stripe
        name: "Lifetime License",
        cost: 299,
        description: "$299 one-time"
      }]
    }

  2. Subscription Prices

    {
      paymentType: "recurring",
      interval: "monthly",          // or "yearly"
      lineItems: [{
        priceId: "price_yyyyy",    // Copy this ID from Stripe
        name: "Pro Monthly",
        cost: 29,
        description: "$29/month"
      }]
    }

Step 3: Configure in JetShip​

Update your billingConfig.ts with the Stripe product and price IDs. See the Billing Schema documentation for detailed configuration examples.

🧪 Testing Your Integration​

Use these test card numbers for different scenarios:

# Successful payment
Card: 4242 4242 4242 4242
Expiry: Any future date
CVC: Any 3 digits

You can find more test card numbers in the Stripe documentation.

Remember to always test thoroughly in Stripe's test mode before going live with real transactions. Happy coding! 🚀