Stripe Setup

This guide covers setting up your Stripe account, configuring payment processing, and implementing webhooks for order status updates.

Prerequisites

A Stripe account
Access to your API server configuration
HTTPS endpoint for webhooks (required for production)

Create Stripe Account

Go to stripe.com
Click Start now or Sign in
Complete account registration
Verify your email address

Complete Business Profile (Production)

For live payments, complete your business profile:

Go to Settings > Business settings
Fill in:
- Business name and details
- Bank account information
- Tax information
Submit for review

You can use test mode immediately without completing this step.

Get API Keys

Retrieve your API keys for both test and production environments.

Access API Keys

Go to Stripe Dashboard
Click Developers > API keys

Copy Test Keys

For development:

Toggle to Test mode (top right)
Copy the Secret key (starts with sk_test_)
Copy the Publishable key (starts with pk_test_)

Test mode uses test card numbers and doesn’t process real payments.

Copy Production Keys (When Ready)

For live payments:

Toggle to Live mode
Click Reveal live key
Copy the Secret key (starts with sk_live_)
Copy the Publishable key (starts with pk_live_)

Keep your secret keys confidential! Never commit them to version control or expose them in client-side code.

Configure Webhook

Webhooks notify your server when payment status changes.

Create Webhook Endpoint

In Stripe Dashboard, go to Developers > Webhooks
Click Add endpoint
Enter your endpoint URL:
- Development: Use Stripe CLI for testing
- Production: https://your-api-domain.com/api/stripe/webhook

Select Events to Listen

Add these events:

payment_intent.succeeded - Payment completed successfully
payment_intent.payment_failed - Payment failed
payment_intent.canceled - Payment canceled

Click Add events to confirm.

Get Webhook Secret

After creating the endpoint, click on it
Click Reveal under Signing secret
Copy the webhook secret (starts with whsec_)

This secret is used to verify webhook signatures and prevent replay attacks.

Test Cards

Use these test card numbers in test mode:

Card Number	Scenario	CVC	Date
`4242 4242 4242 4242`	Successful payment	Any 3 digits	Any future date
`4000 0000 0000 9995`	Payment declined	Any 3 digits	Any future date
`4000 0025 0000 3155`	Requires authentication (3D Secure)	Any 3 digits	Any future date
`4000 0000 0000 0002`	Card declined	Any 3 digits	Any future date

Complete test card list: Stripe Testing Cards

Local Webhook Testing

Test webhooks locally using the Stripe CLI.

Install Stripe CLI

macOS (Homebrew):

brew install stripe/stripe-cli/stripe

Windows (Scoop):

scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
scoop install stripe

Linux:

wget https://github.com/stripe/stripe-cli/releases/latest/download/stripe_linux_amd64.tar.gz
tar -xvf stripe_linux_amd64.tar.gz
sudo mv stripe /usr/local/bin

stripe login

This opens your browser to authorize the CLI.

Forward Webhooks to Local Server

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

The CLI will output a webhook signing secret starting with whsec_. Use this as your STRIPE_WEBHOOK_SECRET during development.

Trigger Test Events

In another terminal, trigger test events:

stripe trigger payment_intent.succeeded
stripe trigger payment_intent.payment_failed

Webhook Implementation

The API server handles three webhook events:

Payment Succeeded

When payment_intent.succeeded is received:

Order status updated to paid
Order confirmation email sent to shop owner
Customer receives payment confirmation

Code reference: /api/src/server.js:52-78

case 'payment_intent.succeeded': {
  const pi = event.data.object
  const orderId = pi.metadata?.order_id
  
  // Update order status to 'paid'
  await supabase
    .from('orders')
    .update({ status: 'paid' })
    .eq('id', orderId)
  
  // Send order recap email
  await sendOrderRecapEmail(orderId)
  break
}

Payment Failed

When payment_intent.payment_failed is received:

Order status updated to failed
User can retry payment or create new order

Code reference: /api/src/server.js:80-89

Payment Canceled

When payment_intent.canceled is received:

Order status updated to canceled
No further action required

Code reference: /api/src/server.js:90-99

Verify Webhook Signatures

The API automatically verifies webhook signatures to prevent tampering: Code reference: /api/src/server.js:38-46

const sig = req.headers['stripe-signature']
let event

try {
  event = stripe.webhooks.constructEvent(
    req.body, 
    sig, 
    STRIPE_WEBHOOK_SECRET
  )
} catch (err) {
  return res.status(400).json({ 
    error: `Webhook Error: ${err.message}` 
  })
}

Always verify webhook signatures in production! This prevents malicious actors from sending fake webhook events.

Payment Flow

Here’s how the complete payment flow works:

Customer Initiates Checkout

User adds items to cart
Clicks “Checkout”
Frontend calls /api/checkout endpoint

Server Creates Payment Intent

API validates cart items and stock
Creates order in database with pending status
Creates Stripe Payment Intent
Returns clientSecret to frontend

Code reference: /api/src/server.js:207-281

Customer Completes Payment

Frontend displays Stripe payment form
Customer enters card details
Stripe processes payment
Payment Intent status changes

Webhook Updates Order

Stripe sends webhook to your server
Server verifies signature
Updates order status based on payment result
Sends confirmation email if successful

Production Checklist

Before going live:

Complete Stripe business profile verification
Switch to live API keys
Update webhook endpoint to production URL
Test webhook with live endpoint
Configure proper error handling
Set up Stripe email receipts
Enable Stripe Radar for fraud detection
Review and configure payment methods (cards, Apple Pay, Google Pay)

Next Steps

Troubleshooting

Webhook Not Receiving Events

Verify endpoint URL is correct and accessible
Check webhook events are selected in Stripe Dashboard
Ensure endpoint returns 200 OK status
Check server logs for errors

Payment Intent Creation Fails

error: "Invalid integer: NaN"

This means the amount calculation failed. Check:

All products have valid prices in database
Cart items include variant_id
Variants exist with non-null prices

Signature Verification Failed

Webhook signature verification failed

Causes:

Wrong STRIPE_WEBHOOK_SECRET
Request body modified before verification
Using wrong secret (test vs. production)

Solution: Ensure you’re using express.raw() middleware for the webhook route:

app.post('/api/stripe/webhook', 
  express.raw({ type: 'application/json' }), 
  webhookHandler
)

Configuration

Deployment

Prerequisites

Create Stripe Account

Get API Keys

Configure Webhook

Test Cards

Local Webhook Testing

Webhook Implementation

Payment Succeeded

Payment Failed

Payment Canceled

Verify Webhook Signatures

Payment Flow

Production Checklist

Next Steps

Troubleshooting

Webhook Not Receiving Events

Payment Intent Creation Fails

Signature Verification Failed

Build docs developers (and LLMs) love

Configuration

Deployment

Documentation Index

​Prerequisites

​Create Stripe Account

​Get API Keys

​Configure Webhook

​Test Cards

​Local Webhook Testing

​Webhook Implementation

​Payment Succeeded

​Payment Failed

​Payment Canceled

​Verify Webhook Signatures

​Payment Flow

​Production Checklist

​Next Steps

​Troubleshooting

​Webhook Not Receiving Events

​Payment Intent Creation Fails

​Signature Verification Failed

Build docs developers (and LLMs) love

Prerequisites

Create Stripe Account

Get API Keys

Configure Webhook

Test Cards

Local Webhook Testing

Webhook Implementation

Payment Succeeded

Payment Failed

Payment Canceled

Verify Webhook Signatures

Payment Flow

Production Checklist

Next Steps

Troubleshooting

Webhook Not Receiving Events

Payment Intent Creation Fails

Signature Verification Failed