Integrations

Payments

Connect your payment provider to see completed payments and refunds in the Revenue dashboard. Matching tracked identities connect payments to their acquisition source.

Connect Stripe

Open Website → Revenue → Settings and choose Connect Stripe. Approve read access to your Stripe account, then return to Databuddy. You do not need to create a webhook or select events for this connection.

The connection receives new payments and imports the 12 months of payments and refunds before you connected, with progress shown in Revenue settings. Browser identity metadata connects payments to visits; older imported payments usually stay unattributed because their visits are no longer available to match. Each Stripe account and environment connects to one website. Payments whose metadata names another website in your organization appear on that website, so one Stripe account can serve several sites. A test-mode connection receives test payments, while a live connection receives live payments.

If Connect Stripe is unavailable in your deployment, use the manual webhook setup below. Paddle also uses that setup.

Add browser identity to your payments

Metadata connects a payment to a tracked visitor. Include the IDs you have: every field is optional, but an ID alone does not prove attribution. Databuddy must find a matching browser event on the same website at or before the payment.

ts
import { getRevenueMetadata } from "@databuddy/sdk";

// In the browser, send the visit's IDs with your checkout request:
await fetch("/api/checkout", {
method: "POST",
body: JSON.stringify({ metadata: getRevenueMetadata() }),
});

// On your server, take only the visit from the request. Who paid comes
// from your own session, so a buyer can't credit someone else:
const visit = Object.fromEntries(
Object.entries(body.metadata ?? {}).filter(
  ([key]) => key === "databuddy_session_id" || key === "databuddy_anonymous_id"
)
);
const databuddyMetadata = {
...visit,
databuddy_client_id: process.env.DATABUDDY_CLIENT_ID,
databuddy_profile_id: user.id,
};

await stripe.paymentIntents.create({
amount,
currency,
metadata: databuddyMetadata,
});

// For recurring billing, attach it to the Subscription too.
await stripe.subscriptions.create({
customer,
items: [{ price: priceId }],
metadata: databuddyMetadata,
});

getRevenueMetadata() returns databuddy_client_id, databuddy_session_id, databuddy_profile_id and databuddy_anonymous_id, leaving out any ID it doesn't have. Pass your Client ID, as in getRevenueMetadata(clientId), if you call it before the tracker loads.

A buyer can edit what their browser sends. Keep only the session and anonymous IDs from the request, and set the Client ID and profile ID on your server; leave out databuddy_profile_id for a guest checkout. Passing the browser's metadata through unchanged lets a buyer credit a payment to another user, account or website.

To keep an account's plan, billing status and MRR current, set databuddy_group_<type> on the Subscription from your server, for the account being billed.

For Stripe Checkout, put the same metadata on the underlying payment or subscription:

ts
// One-time Checkout payment:
await stripe.checkout.sessions.create({
...checkoutOptions,
mode: "payment",
payment_intent_data: { metadata: databuddyMetadata },
});

// Subscription Checkout:
await stripe.checkout.sessions.create({
...subscriptionCheckoutOptions,
mode: "subscription",
subscription_data: { metadata: databuddyMetadata },
});

Stripe does not automatically copy PaymentIntent metadata to future subscription invoices. Put the IDs on the Subscription (or subscription_data.metadata when using Checkout) so recurring revenue stays attributable.

FieldWhat it enables
Session IDTies revenue to the exact visit, referrer, and campaign
Anonymous IDMatches a browser-recorded anonymous identity when that identity can still be resolved
Profile IDTies revenue to the identified user, see Identify users

Anonymous IDs follow your browser tracking privacy settings. Databuddy reuses the identity recorded by the browser instead of generating a new payment-delivery-day identity. Prefer session and profile IDs for delayed payments and renewals; anonymous-only matching can become unavailable after a privacy salt expires. Profile IDs are your own opaque user IDs and are stored as sent.

Paddle checkout opens in the browser, so the buyer can edit its custom data. To make profile_id trustworthy, create the transaction on your server with the signed-in user's ID in custom_data, then open checkout for that transaction.

Only browser events provide the referrer, campaign, country, and device used for revenue attribution. Server-side track() calls through the Node SDK or the /track API are stored as custom events. A session ID minted on the server cannot supply browser attribution; another matching tracked identity is needed. Take sessionId from getIds() in the browser and pass it to your server, rather than generating one server-side.

Databuddy first tries the payment's tracked session, then its profile ID, then its anonymous ID. If none matches, it can reuse a previously verified session for the same provider customer on the same website. Ambiguous sessions and sessions belonging to another identified profile are not credited. Stripe invoice context can supply IDs missing from a payment webhook.

Revenue attribution measures attributed completed-payment revenue divided by total completed-payment revenue in the selected currency. Refunds are reported separately. Profile revenue can show a payment associated with a user even when no browser event exists to attribute its acquisition source.

Verify it works

Send a test payment (Stripe test mode works), then check Website → Revenue. The transaction appears within seconds of the webhook delivery. If you passed a profile ID, the revenue also shows on that user in Website → Users.

Troubleshooting

  • Nothing appears: check the connection in Revenue settings, the selected website, currency and date range, and whether the payment is in the connection's test or live environment. For manual webhooks, also verify the endpoint and signing secret.
  • Revenue appears but isn't attributed: check for a matching browser event before the payment on the same website. Missing IDs, untracked sessions, conflicting profiles, and events occurring after the payment cannot establish attribution. An existing verified customer session can attribute later renewals without fresh payment metadata.
  • A manual payment flow never attributes: check that your endpoint subscribes to every required event. Stripe subscribes an endpoint to a fixed event list, and adding a new payment flow does not update it. Revenue settings shows when Databuddy last recorded each event, which helps you spot a type that stopped arriving, but an event that simply has not happened yet (a refund, a failed payment) also shows no activity, so compare it against the event list in your Stripe dashboard rather than treating it as proof.
  • A session ID you sent isn't recognised: it has to come from the browser tracker. IDs generated on the server, or sent through server-side track(), never produce a joinable session.
  • Stripe shows failed deliveries: regenerating webhook URLs invalidates the old path, so update Stripe after regenerating.

Manual webhook setup

This fallback is for Paddle and deployments without the Stripe App connection. App-connected Stripe accounts use the managed delivery path, so old manual retries cannot overwrite their reconciled payments.

Generate your webhook URL

  1. Open your Databuddy dashboard and go to Website → Revenue.
  2. Click Generate webhook URLs. You get one URL per provider, each with a unique secret path.
  3. Keep this page open; you'll paste the URL into your provider next.

Add the webhook to your provider

In the Stripe dashboard, add an endpoint with your generated URL. For subscriptions, select these two events:

EventPurpose
invoice.paidLinks the invoice to its visitor metadata
invoice_payment.paidRecords the payment made against the invoice

Databuddy expects Stripe API version 2025-05-28.basil or later, because invoice_payment.paid was introduced in that version and is the canonical money event for anything billed through an invoice. If you also accept one-time payments, enable payment_intent.succeeded. One-time payments without invoicing only need that event when visitor metadata is on the PaymentIntent.

Checkout Session metadata stays on the Session unless you also set payment_intent_data.metadata. Keep checkout.session.completed and checkout.session.async_payment_succeeded enabled so Databuddy can link one-time Checkout metadata to its payment, including delayed payment methods. These additional events link metadata; payment events supply the revenue amount. They are unnecessary when your metadata is already on the PaymentIntent.

invoice.paid and invoice_payment.paid carry different halves of the same fact, and you need both. The payment event carries the amount but references its invoice by ID only, so it cannot see your metadata. The invoice event carries the metadata but no payment amount, because Stripe does not include the invoice's payments list in webhook deliveries. Databuddy records the amount from the payment event and joins the metadata from the invoice event, which is why a subscription payment stays unattributed if only one of the two is enabled. Order does not matter, and redelivering either event is safe.

Optionally enable charge.refunded for refunds, payment_intent.payment_failed and invoice.payment_failed for failure diagnostics, and payment_intent.canceled for cancellations. These are not required to attribute successful payments. To keep account billing current, also enable customer.subscription.created, customer.subscription.updated and customer.subscription.deleted.

Paste the endpoint's signing secret into the Revenue settings so Databuddy can verify each delivery.

How is this guide?