The Prince Academy株式会社 | Handling Successful Payments and Webhooks | Implementing Basic Payment Flows with Stripe Checkout | Stripe for Next.js: A Developer's Guide to Seamless Payments

Congratulations! You've successfully integrated Stripe Checkout and guided your users through the payment process. But the journey doesn't end when the user sees a success page. In the real world, you need robust mechanisms to confirm payments, update your database, and potentially fulfill orders. This is where handling successful payments and leveraging Stripe Webhooks become crucial.

When a payment is successful with Stripe Checkout, Stripe will redirect the user back to your specified success_url. While this is a good user experience, it's not a reliable way to programmatically confirm the payment. The redirect can fail, or a user might close their browser before it completes. Therefore, we must rely on Stripe Webhooks for reliable payment confirmation.

Webhooks are automated messages sent by Stripe to your application when specific events occur. For payment processing, the most critical webhook event is checkout.session.completed. This event is sent when a Checkout Session is successfully completed. By setting up an endpoint to listen for this event, you can reliably update your system.

Here's a high-level overview of how the webhook process works:

graph LR
    A[User Completes Payment in Stripe Checkout] --> B{Stripe Server}; B --> C{Triggers checkout.session.completed Event}; C --> D[Your Webhook Endpoint]; D --> E{Verify Event Signature}; E -- Valid --> F[Update Database/Fulfill Order]; E -- Invalid --> G[Log Error/Ignore];

To implement this, you'll need to:

Create a Webhook Endpoint: This will be a new API route in your Next.js application that Stripe can send POST requests to.

import { stripe } from '@/lib/stripe'; // Assuming you have a stripe client initialized
import Stripe from 'stripe';

export async function POST(request) {
  const signature = request.headers.get('stripe-signature');
  const signingSecret = process.env.STRIPE_WEBHOOK_SECRET;

  if (!signingSecret) {
    console.error('Stripe webhook secret not configured.');
    return new Response('Internal Server Error', { status: 500 });
  }

  let event;

  try {
    event = stripe.webhooks.constructEvent(
      await request.text(),
      signature,
      signingSecret
    );
  } catch (err) {
    console.error(`Webhook signature verification failed: ${err.message}`);
    return new Response('Unauthorized', { status: 401 });
  }

  // Handle the event
  switch (event.type) {
    case 'checkout.session.completed':
      const session = event.data.object as Stripe.Checkout.Session;
      // Fulfill the purchase...
      console.log('Checkout session completed:', session);
      // Add your order fulfillment logic here
      break;
    // ... handle other event types
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  // Return a response to acknowledge receipt of the event
  return new Response(JSON.stringify({ received: true }), {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
    },
  });
}

graph LR A[User Completes Payment in Stripe Checkout] --> B{Stripe Server}; B --> C{Triggers checkout.session.completed Event}; C --> D[Your Webhook Endpoint]; D --> E{Verify Event Signature}; E -- Valid --> F[Update Database/Fulfill Order]; E -- Invalid --> G[Log Error/Ignore];

import { stripe } from '@/lib/stripe'; // Assuming you have a stripe client initialized import Stripe from 'stripe'; export async function POST(request) { const signature = request.headers.get('stripe-signature'); const signingSecret = process.env.STRIPE_WEBHOOK_SECRET; if (!signingSecret) { console.error('Stripe webhook secret not configured.'); return new Response('Internal Server Error', { status: 500 }); } let event; try { event = stripe.webhooks.constructEvent( await request.text(), signature, signingSecret ); } catch (err) { console.error(`Webhook signature verification failed: ${err.message}`); return new Response('Unauthorized', { status: 401 }); } // Handle the event switch (event.type) { case 'checkout.session.completed': const session = event.data.object as Stripe.Checkout.Session; // Fulfill the purchase... console.log('Checkout session completed:', session); // Add your order fulfillment logic here break; // ... handle other event types default: console.log(`Unhandled event type: ${event.type}`); } // Return a response to acknowledge receipt of the event return new Response(JSON.stringify({ received: true }), { status: 200, headers: { 'Content-Type': 'application/json', }, }); }