Passing Custom Data to Stripe Checkout for Server-Side Processing
When integrating Stripe Checkout with server-side rendering, a common friction point is retrieving specific application dataâlike product IDs or order slugsâduring the checkout.session.completed event. The standard checkout flow abstracts away much of the transactional context; by design, it exposes only high-level metadata such as product names, descriptions, and images. If your fulfillment logic relies on a unique identifier rather than querying a database solely off a product name, you need to inject that data into the session before Stripe creates the final object.
You cannot rely on the client-side checkout.js library alone to pass custom parameters if you require them to be persisted in the backend context for webhook verification. The solution is to create a server-generated Checkout Session. This approach gives you full control over the metadata attached to the session, ensuring that when Stripe pings your endpoint, the payload contains exactly what you need to fulfill the order.
Creating the Server-Side Session
Instead of redirecting users directly to a hosted payment page via client-side code, you must first create the session on your server using the Stripe API. In this step, you attach your custom data to the metadata field of the session object. Stripe treats metadata as a flat key-value store intended for internal use; it is not displayed to the customer but is fully accessible during webhook events.
When creating the session via your backend code (whether using the PHP SDK or another language), include your order ID, user ID, or any other slug in the metadata:
$session = \Stripe\Checkout\Session::create([
'payment_intent_data' => [
// Your payment intent logic here
],
'mode' => 'payment',
'success_url' => $successUrl . '&session_id={CHECKOUT_SESSION_ID}',
'cancel_url' => $cancelUrl,
'metadata' => [
'product_id' => 'prod_123',
'user_id' => 'usr_456',
'order_slug' => 'premium-audio-pack'
],
'line_items' => [[
'price_data' => [
'currency' => 'usd',
'product_data' => [
'name' => 'Premium Audio Pack',
'images' => ['https://example.com/image.jpg']
],
'unit_amount' => 2900, // in cents
],
'quantity' => 1
]]
]);
// Return the session ID to your frontend or redirect immediately
return response()->json(['session_id' => $session->id]);
By populating the metadata array here, you ensure that when the payment succeeds and Stripe triggers the webhook, your application receives these values directly in $session->metadata. This eliminates the need for expensive database lookups based on product names or descriptions.
Handling the Webhook Payload
When your endpoint receives the checkout.session.completed event, you can immediately access the custom identifiers you stored earlier. The structure of the webhook payload remains consistent regardless of how the session was created. Your existing verification logic handles security by validating the signature, but the data extraction becomes straightforward once the metadata is present.
Inside your webhook handler, check the metadata property:
if ($event->type == 'checkout.session.completed') {
$session = $event->data->object;
// Access custom data passed during session creation
$productId = $session->metadata['product_id'] ?? null;
$userId = $session->metadata['user_id'] ?? null;
$orderSlug = $session->metadata['order_slug'] ?? null;
if ($productId && $userId) {
// Fulfill the purchase using the specific IDs
$this->db->insertAudioPurchase([
'product_id' => $productId,
'user_id' => $userId,
'order_slug' => $orderSlug
]);
}
}
This pattern ensures that your fulfillment logic is decoupled from the Stripe UI. Even if you change the product name or description on the Stripe dashboard later, the unique IDs in your database remain intact because they were baked into the session metadata at creation time.
Trade-offs and Security Considerations
While passing custom data via metadata is powerful, it is critical to remember that metadata is a simple string key-value store. Do not attempt to serialize complex objects or large datasets here. Furthermore, while Stripe verifies webhook signatures to prevent tampering, you must validate the signature on your own server before trusting any data in the payload. Never rely solely on client-side tokens for sensitive operations like order fulfillment without backend verification.
If you are building a SaaS application where you might need more robust session management or deeper integration features beyond basic checkout flows, exploring resources from LaravelCompany can provide additional context on scaling these integrations within the Laravel ecosystem. However, for standard server-to-server data passing, the metadata approach described here is the canonical and most reliable method.