Stripe Setup

1. Create a Stripe Account and Get API Keys

1. Go to the Stripe Dashboard  and log in (or create a new account).
2. If you haven’t already, activate your account by providing business details (you can use test mode first).
3. Navigate to Developers → API keys.
4. Copy the following keys:
   • Publishable key (starts with pk_test_)
   • Secret key (starts with sk_test_)

2. Add Stripe Environment Variables

Add the keys to your .env.local file:

STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=           # You will fill this later after creating the webhook
CONVEX_FEATURED_PRICE=4900       # Price for featured status (in cents, $49.00)

• STRIPE_SECRET_KEY – your secret key (keep it safe, never expose it client‑side).

• NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY – your publishable key (safe to use on the frontend).

• STRIPE_WEBHOOK_SECRET – will be set after configuring the webhook (step 5).

• CONVEX_FEATURED_PRICE – price for featuring a tool for 30 days (default: 4900 = $49). You can change it later by running npx convex env set CONVEX_FEATURED_PRICE 4900.

3. Create Products for Ad Placements in Stripe

Dirly allows users to purchase ad placements. Each placement is a one‑time payment (not a subscription) that activates a 30‑day campaign. In Stripe, you need to create products with a one‑time price.

1. In the Stripe Dashboard, go to Products → Add Product.

2. Create three separate products with the following details:

Pricing

For each product:

• Set the Pricing model to One‑time.

• After creation, copy the Price ID (starts with price_). You will need these IDs later to configure ad placements in the admin panel.

4. Manage Ad Placements via Admin Panel

Dirly includes a full admin interface for managing ad placements. You can create, edit, delete, or load default placements without touching the database directly.

1. Log in to your Dirly admin panel (you need admin privileges).

2. Navigate to /admin/placements.

3. You will see a list of existing placements (if any).

4. Use the Load Default Placements button to automatically insert the three default ad placements (Top Banner, Catalog Card, Project Page Ad Card) with predefined slugs, descriptions, and prices.

5. To edit a placement, click the Edit icon (pencil). You can modify:

• Name – display name.

• Slug – URL‑friendly identifier (used in code).

• Description – shown to users.

• Price (one‑time) – in cents (e.g., 6900 for $69).

• Stripe Price ID – the price_... you copied from Stripe.

• Available – whether the placement is active.

6. To create a new placement, click New Placement.

7. To delete a placement, use the Delete icon (trash).

5. Configure the Webhook in Stripe Dashboard

The webhook listens for successful payments (payment_intent.succeeded) and updates your database accordingly (activates ad campaigns, grants featured status).

For Local Development

You need to expose your local server to the internet so Stripe can reach it. Use Stripe CLI (recommended) or ngrok.

A. Using Stripe CLI:

Install the Stripe CLI from stripe.com/docs/stripe-cli.

Run:

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

The CLI will output a webhook signing secret. Copy it and add to your .env.local:

STRIPE_WEBHOOK_SECRET=whsec_...

B. Using ngrok:

1. Start your Next.js app (npm run dev).

2. In another terminal, run:

ngrok http 3000

3. Copy the generated HTTPS URL (e.g., https://abc123.ngrok.io).

4. In Stripe Dashboard, go to Developers → Webhooks → Add endpoint.

5. Enter your ngrok URL + /api/stripe-webhook (e.g., https://abc123.ngrok.io/api/stripe-webhook).

6. Select Events to send – choose payment_intent.succeeded (this is the event that fires after a successful one‑time payment).

7. Click Add endpoint.

8. After creation, click Click to reveal in the Signing secret section and copy the secret. Add it to your .env.local as STRIPE_WEBHOOK_SECRET.

For Production

When your app is live on Vercel (or another platform), create a new webhook endpoint pointing to:

https://yourdomain.com/api/stripe-webhook

Subscribe to payment_intent.succeeded, copy the signing secret, and set it as STRIPE_WEBHOOK_SECRET in your hosting environment (e.g., Vercel Environment Variables).

6. Payment Flow (Already Implemented)

Your application includes the following API routes to create Payment Intents and handle the webhook:

• Ad placements: app/api/create-payment-intent/route.ts – creates a Payment Intent for a selected ad placement, using the price from the adPlacements table.

• Featured tool: app/api/create-featured-payment-intent/route.ts – creates a Payment Intent for featuring a tool, using the price stored in the CONVEX_FEATURED_PRICE environment variable.

• Webhook handler: app/api/stripe-webhook/route.ts – listens for payment_intent.succeeded events. When received, it:

  • For ad placements: creates a new campaign record in the adCampaigns table, active for 30 days.

  • For featured tool: sets the tool’s featured field to true with an expiration date (30 days from payment).

No code changes are required – everything is already wired up.

7. Test the Integration

1. Make sure your app is running and the webhook is listening (Stripe CLI or ngrok active).

2. Go to your /advertise page, select an ad placement, fill in the creative details, and click Subscribe (or the payment button).

3. You will be redirected to Stripe’s Checkout page (or use a Payment Element if integrated). Use the test card:

• Card number: 4242 4242 4242 4242

• Expiry: any future date

• CVC: any 3 digits

4. After successful payment, you should be redirected back to your app.

5. Check that the ad campaign appears in the admin panel (/admin/campaigns) and on the frontend (if approved).

6. For featured tool: go to a tool’s page (you must be the owner of an approved tool), click Feature for $49, complete the payment, and verify that the tool now displays a “Featured” badge.

7. In Stripe Dashboard, navigate to Events to confirm that the payment_intent.succeeded event was sent and received successfully.