Stripe

Connect Stripe payments to Databuddy's analytics to track revenue, conversion funnels, and customer behavior. This integration links payment events to your website analytics for complete revenue attribution.

Overview

The Stripe integration captures:

• Payment Intents: Track payment attempts, successes, and failures
• Charges: Monitor successful payments and refunds
• Refunds: Track refund events and amounts
• Revenue Attribution: Link payments to specific user sessions and marketing campaigns

Quick Setup (Webhooks Only)

For basic revenue tracking without session attribution:

https://basket.databuddy.cc/webhooks/stripe/your_unique_hash

Advanced: Session Attribution

For full revenue attribution that links payments to user sessions, you need to pass Databuddy tracking IDs in your Stripe checkout metadata.

How Session Tracking Works

Databuddy automatically handles session and user IDs:

• Session ID: Automatically generated and stored in sessionStorage as did_session
• Session Format: sess_{timestamp}_{random_string} (e.g., sess_lm8k9x_abc123def456)
• Anonymous ID: Automatically generated and stored in localStorage as did
• Anonymous Format: anon_{uuid} (e.g., anon_123e4567-e89b-12d3-a456-426614174000)

When you pass these IDs to Stripe via metadata, Databuddy can:

• Link payment events to specific user sessions
• Track the complete customer journey from first visit to purchase
• Attribute revenue to marketing campaigns and traffic sources
• Calculate conversion rates and customer lifetime value

Implementation

Using the Databuddy SDK (Recommended)

import { getTrackingIds } from '@databuddy/sdk';

// Get both session ID and anonymous ID
const { anonId, sessionId } = getTrackingIds();

// Send to your backend when creating checkout
await fetch('/create-checkout-session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
  sessionId,
  anonymousId: anonId,
  clientId: 'your_databuddy_client_id',
  // ... other checkout data
}),
});

Server-Side: Node.js/JavaScript

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

const session = await stripe.checkout.sessions.create({
payment_method_types: ['card'],
mode: 'payment',
line_items: [
  {
    price: 'price_1234567890',
    quantity: 1,
  },
],
success_url: 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
cancel_url: 'https://yoursite.com/cancel',

// REQUIRED: Set metadata on payment intent (this propagates to all webhook events)
payment_intent_data: {
  metadata: {
    databuddy_client_id: 'your_databuddy_client_id', // Required for webhook processing
    databuddy_session_id: sessionId, // Required for analytics tracking
    databuddy_anonymous_id: anonymousId, // Optional: For anonymous user tracking
  },
},
});

Server-Side: Python

import stripe

stripe.api_key = os.environ['STRIPE_SECRET_KEY']

session = stripe.checkout.Session.create(
  payment_method_types=['card'],
  mode='payment',
  line_items=[{
      'price': 'price_1234567890',
      'quantity': 1,
  }],
  success_url='https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url='https://yoursite.com/cancel',
  
  # REQUIRED: Set metadata on payment intent (this propagates to all webhook events)
  payment_intent_data={
      'metadata': {
          'databuddy_client_id': 'your_databuddy_client_id',
          'databuddy_session_id': session_id,
          'databuddy_anonymous_id': anonymous_id,
      },
  },
)

React/Next.js Example

import { getTrackingIds } from '@databuddy/sdk';
import { useState } from 'react';

function CheckoutButton({ priceId, productName }) {
const [isLoading, setIsLoading] = useState(false);

const handleCheckout = async () => {
  setIsLoading(true);

  try {
    // Get tracking IDs from Databuddy SDK
    const { anonId, sessionId } = getTrackingIds();

    const response = await fetch('/api/create-checkout-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        priceId,
        sessionId,
        anonymousId: anonId,
        clientId: process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID,
      }),
    });

    const { url } = await response.json();
    window.location.href = url;
  } catch (error) {
    console.error('Checkout error:', error);
    setIsLoading(false);
  }
};

return (
  <button onClick={handleCheckout} disabled={isLoading}>
    {isLoading ? 'Processing...' : `Buy ${productName}`}
  </button>
);
}

Metadata Fields Reference

Testing

Test Mode Setup

1. Use Stripe Test Mode: Ensure your webhook is configured for test mode
2. Use Test Cards: Use Stripe's test card numbers
3. Monitor Webhook Events: Check your Databuddy dashboard for incoming events

Test Card Numbers

• Successful Payment: 4242424242424242
• Payment Requires Authentication: 4000002500003155
• Payment Fails: 4000000000000002
• Insufficient Funds: 4000000000009995

Verify Data Flow

1. Create a test purchase using a test card
2. Check Stripe Dashboard: Verify the webhook was called successfully
3. Check Databuddy Dashboard: Confirm payment data appears in your analytics
4. Verify Attribution: Ensure payment is linked to the correct session

Troubleshooting

Missing databuddy_client_id Error

Problem: Webhook receives events but shows "Missing required client_id" error

Solutions:

• Ensure databuddy_client_id is set in payment_intent_data.metadata
• Verify the databuddy_client_id matches your Databuddy Client ID exactly
• Don't set metadata on checkout session - only use payment_intent_data.metadata

Session ID Not Linking

Problem: Payments appear in Databuddy but aren't linked to user sessions

Solutions:

• Verify databuddy_session_id in metadata contains the correct session ID
• Use getSessionId() from @databuddy/sdk or sessionStorage.getItem('did_session')
• Ensure Databuddy has initialized before creating the checkout session
• Make sure the session hasn't expired (30-minute timeout)

Webhook Signature Verification Failed

Problem: Webhook returns "Invalid signature" error

Solutions:

• Verify webhook secret is correct (starts with whsec_)
• Ensure webhook secret matches between Stripe and Databuddy
• Check that webhook endpoint URL is exactly as configured

Related Resources