# Stripe Integration

> Discover how to connect Stripe payments with Ours Privacy to track payment events and user data, with privacy controls on what each destination receives.

Source: https://docs.oursprivacy.com/docs/stripe

The **Stripe Integration** lets you track payment events and user data from Stripe while routing everything through Ours Privacy. There are two approaches depending on where your Stripe events originate:

* **Browser-side**: track checkout and payment events directly from your frontend using the Ours Privacy Web SDK.
* **Server-side (webhook source)**: receive Stripe webhook events on your server and forward them into Ours Privacy as events.

Use browser-side tracking for checkout funnel visibility, and the webhook source for reliable post-payment events (charges, subscriptions, refunds) that happen outside the browser.

***

## Browser-Side Tracking

### Custom Checkout

If you're using a custom payment form (e.g. Stripe Elements or the Payment Element), fire events directly using the Ours Privacy Web SDK at each stage of the checkout flow:

```javascript
// User begins checkout
ours('track', 'CheckoutStarted', {
  amount: 1000, // Amount in cents
  currency: 'usd',
});

// Payment attempt submitted
ours('track', 'PaymentAttempt', {
  amount: 1000,
  currency: 'usd',
  paymentMethod: 'card',
});

// Payment confirmed
ours('track', 'PaymentSuccess', {
  amount: 1000,
  currency: 'usd',
  paymentMethod: 'card',
  transactionId: 'pi_123456789',
});

// Payment failed
ours('track', 'PaymentFailure', {
  amount: 1000,
  currency: 'usd',
  paymentMethod: 'card',
  error: 'insufficient_funds',
});
```

### Stripe Checkout (hosted page)

When redirecting to a Stripe-hosted Checkout page, the browser leaves your site, so you need to identify the user before the redirect and capture the confirmation on the success page redirect.

**Step 1: Identify before redirecting:**

```javascript
// Capture the user's email before leaving your site
ours('identify', { email: 'user@example.com' });

// Then redirect to your server to create a Checkout Session
// (never create Checkout Sessions in the browser; keep your secret key server-side)
window.location.href = '/api/create-checkout-session';
```

**Step 2: Track the success page:**

Stripe appends `?session_id={CHECKOUT_SESSION_ID}` to your success URL. Read it on page load:

```javascript
// On your success page
const params = new URLSearchParams(window.location.search);
const sessionId = params.get('session_id');

ours('track', 'PaymentSuccess', {
  transactionId: sessionId,
  source: 'stripe_checkout',
});
```

### Allowlist your events

After testing, log in to the Ours Privacy dashboard and go to **Sources → Recent Events → Allowed Events List**. Add each event name you configured (`CheckoutStarted`, `PaymentAttempt`, `PaymentSuccess`, `PaymentFailure`) so they are forwarded to your destinations.

***

## Server-Side Webhook Source

For events that happen outside the browser (successful charges, subscription renewals, refunds, disputes), use Ours Privacy as a Stripe webhook receiver. It creates a source-specific webhook URL that accepts Stripe event payloads and maps them into events in your account.

### Setup

1. In the Ours Privacy dashboard, go to **Sources** and create a new **Webhook** source. Copy the webhook URL.
2. In your [Stripe Dashboard → Developers → Webhooks](https://dashboard.stripe.com/webhooks), click **Add endpoint**, paste the Ours Privacy webhook URL, and select the events you want to forward (e.g. `payment_intent.succeeded`, `customer.subscription.created`, `charge.refunded`).
3. Back in Ours Privacy, configure the **field mappings** to extract the properties you need from the Stripe event payload (e.g. map `data.object.amount` → `amount`, `data.object.customer` → `userId`).

### Recommended events to forward

| Stripe event                    | Suggested Ours Privacy event name |
| ------------------------------- | --------------------------------- |
| `payment_intent.succeeded`      | `PaymentSuccess`                  |
| `payment_intent.payment_failed` | `PaymentFailure`                  |
| `checkout.session.completed`    | `CheckoutCompleted`               |
| `customer.subscription.created` | `SubscriptionStarted`             |
| `customer.subscription.deleted` | `SubscriptionCancelled`           |
| `charge.refunded`               | `Refunded`                        |

> **Note:** Stripe webhook events are server-generated and do not carry a browser visitor ID. To tie them back to a known user, map the Stripe `customer` ID or email to the `userId` or `email` fields in your Ours Privacy mapping configuration.

***

## Best Practices

* **Never track raw credit card details.** Only use Stripe-provided tokens and IDs.
* **Identify before redirecting.** For hosted Checkout, call `ours('identify')` with the user's email before the redirect so the payment event links to the right visitor profile.
* **Prefer the webhook source for billing events.** Browser-side tracking can be blocked or missed; server-side webhooks are authoritative for charges, subscriptions, and refunds.
* **One key per event type.** Keep browser-side events (funnel, UX) separate from server-side events (billing, fulfillment) so you can route them to different destinations independently.

***

## Next Steps

* [Webhook Source setup](https://docs.oursprivacy.com/docs/webhooks): full reference for configuring field mappings
* [Allowed Events](https://docs.oursprivacy.com/docs/platform-api/allowed-events): how to allowlist events for forwarding to destinations
* [Destinations](https://docs.oursprivacy.com/docs/destination-overview): forward payment events to your ad platforms, CRM, or data warehouse
