# Stripe integration

<Aside type="caution" icon="setting" title="Developer assistance needed">
You will need help from your development team to pass metadata (journey, user, device) when creating Stripe Checkout Sessions. Share this guide with them.
</Aside>

[Stripe](https://stripe.com/) is a payment platform that lets you accept payments and manage subscriptions. Integrating Stripe with Pushwoosh lets you track payments and subscriptions in [campaigns](/product/customer-journey/pushwoosh-journey-overview/), analyze revenue by journey and product, [segment users](/product/audience-data-and-segmentation/segmentation/) by payment events, and use [ManyMoney AI](/product/pushwoosh-ai/ai-assistant/) for revenue insights.

## Integration overview

### Integration type

**Source:** Payment and subscription events are sent from Stripe to Pushwoosh.

### Prerequisites

To set up the Stripe integration with Pushwoosh, ensure the following:

* You have an active Pushwoosh account.
* You have a Stripe account.


### Glossary (mapping entity names if they are different)

The table below shows how Stripe entities map to Pushwoosh. This mapping is achieved by passing the corresponding fields as metadata when you create a Checkout Session (see [Metadata configuration](#metadata-configuration)).

| Stripe | Pushwoosh |
|--------|-----------|
| Customer | `user_id` (required), `device_id` (optional) in metadata |
| Payment / Charge | Event **StripePaymentSucceeded** (`charge.succeeded`) |
| Invoice (paid) | Event **StripeInvoicePaid** (`invoice.paid`) |
| Subscription | **StripeSubscriptionCreated** + attributes in **StripeInvoicePaid** |
| Product / Price | `product_id`, `product_name` in metadata and event attributes |
| Campaign (journey) | `journey_uuids` in metadata |

### Synchronized entities

* Payment events (one-time payments, subscription invoices)
* Subscription events (subscription created, subscription invoice paid)


### How does the integration work?

After you connect your Stripe account to Pushwoosh via **Stripe Connect**, Pushwoosh receives payment and subscription data from Stripe. You can link each transaction to a campaign and user or device by passing metadata when creating a Checkout Session (see [Metadata configuration](#metadata-configuration)). 

Pushwoosh creates events you can use for [segmentation](/product/audience-data-and-segmentation/segmentation/) and analytics. 

##### Data flow

1. You connect your Stripe account to Pushwoosh once via **Stripe Connect** in **Settings** → **3rd-party integrations**.
2. When creating a Checkout Session, you pass metadata so the payment can be attributed later (see [Metadata configuration](#metadata-configuration)).
3. When a payment or subscription event occurs in Stripe (e.g. `charge.succeeded` for one-time, `invoice.paid` for subscription), Stripe sends the data to Pushwoosh.
4. Pushwoosh creates the corresponding events and uses the metadata for attribution. This data appears in Finance Overview, Audience → Events, and ManyMoney.


### Use cases
##### Track payments
Automatically receive information about all successful payments and subscriptions.

##### Link payments to campaigns
Associate transactions with specific [customer journeys](/product/customer-journey/pushwoosh-journey-overview/) by passing metadata (see [Metadata configuration](#metadata-configuration)).

##### Analyze revenue
View income by campaigns, products, users, and devices.

##### Segment your audience
[Create segments](/product/audience-data-and-segmentation/segmentation/create-segments/by-events/) based on payment events.

##### AI analytics
[ManyMoney AI](/product/pushwoosh-ai/ai-assistant/) assistant automatically receives payment and subscription statistics and can make decisions based on this data.

## Set up the integration

### Connect Stripe to Pushwoosh

1. Open any Pushwoosh application (Stripe account is linked to your entire account, not a specific application) and navigate to **Settings** → **3rd-party integrations**.
2. Find the **Stripe** card and click the **LOGIN PAGE** button.

![Settings page with 3rd-party integrations section and Stripe card with LOGIN PAGE button](/integrations-stripe-integration-1.webp)

3. You will be redirected to the Stripe authorization page.

![Stripe authorization page with account selection and Connect button](/integrations-stripe-integration-2.webp)

4. On the Stripe page, enter your email and click **Continue**.
5. Log in to your Stripe account (or create a new one). If you have multiple accounts, select the account you want to connect.
6. Click **Connect** to confirm.
7. After successful authorization, you will be redirected back to Pushwoosh. The integration status will change to **Connected**.

![3rd-party integrations page showing Stripe card with Connected status](/integrations-stripe-integration-3.webp)

### Disconnect the integration

##### Method 1. Via Pushwoosh

1. Go to **Settings** → **3rd-party integrations**.
2. Find the **Stripe** card and click the **SETTINGS** button.
3. In the popup window, click the **Disconnect** button.

![Stripe card SETTINGS popup with Disconnect button in 3rd-party integrations](/integrations-stripe-integration-4.webp)


##### Method 2. Via Stripe Dashboard

1. Log in to [Stripe Dashboard](https://dashboard.stripe.com).
2. Go to **Settings** → **Team and security** → **Installed apps**.
3. Find the application in the **Connect Extensions** section.

![Stripe Dashboard Settings, Team and security, Installed apps, Connect Extensions section](/integrations-stripe-integration-5.webp)

When you disconnect through Stripe, Pushwoosh automatically receives a notification and removes the integration.

## Metadata configuration

Stripe sends payment events to Pushwoosh, but without extra data Pushwoosh cannot tell which campaign or which user the payment belongs to. When you pass metadata at Checkout Session creation (campaign IDs, user or device ID, product), each payment is attributed to the right journey and user. 

You then see revenue by campaign in Finance Overview, build segments by payer, and use ManyMoney with correct attribution. 

### Available metadata fields

| Field | Description | Required | Example |
|-------|-------------|----------|---------|
| `journey_uuids` | Campaign (journey) IDs separated by semicolons | No | `bfab4bc0-b0a5-414b-befc-4aaddc429b0e;a2bff710-6b49-44d1-96a7-3232feeca6e9` |
| `user_id` | User identifier. Required for event collection and for `device_id` to be applied | Yes | `user_12345` or `email@example.com` |
| `device_id` | Device Hardware ID (HWID). | No | `hwid_abc123` |
| `product_id` | Product ID | No | `prod_premium` |
| `product_name` | Product name | No | `Premium Plan` |

<Aside type="caution" title="Important">

- Without `user_id`, events are not collected and `device_id` is ignored. For comprehensive analytics, also provide `journey_uuids` and `device_id`.

- `journey_uuids` is optional and can only be set via metadata. Stripe does not supply campaign or journey data, so pass it when creating the Checkout Session if you want revenue attributed to a journey.

- `product_id` and `product_name` are optional. Pushwoosh uses metadata first. If either is missing in metadata, it is taken from Stripe when available. If neither source has a value, the field is not stored.

</Aside>

### Passing metadata via Checkout Session

Metadata is passed when creating a Checkout Session depending on the payment type:

| Payment type | Parameter | Stripe event |
|--------------|-----------|--------------|
| One-time payment (`mode=payment`) | `payment_intent_data[metadata]` | `charge.succeeded` |
| Subscription (`mode=subscription`) | `subscription_data[metadata]` | `invoice.paid` |

### Metadata priority during processing

**For subscriptions** (`invoice.paid` event):

```text
Invoice metadata → if empty → Subscription metadata
```

**For one-time payments** (`charge.succeeded` event):

```text
Charge metadata (from payment_intent_data)
```

## Creating a checkout session via Stripe API (curl)

##### One-time payment (`mode=payment`)

```bash
curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_live_YOUR_SECRET_KEY: \
  -d "mode=payment" \
  -d "success_url=https://example.com/success" \
  -d "cancel_url=https://example.com/cancel" \
  -d "line_items[0][price]=price_1234567890" \
  -d "line_items[0][quantity]=1" \
  -d "payment_intent_data[metadata][journey_uuids]=bfab4bc0-b0a5-414b-befc-4aaddc429b0e" \
  -d "payment_intent_data[metadata][user_id]=user_12345" \
  -d "payment_intent_data[metadata][device_id]=hwid_abc123" \
  -d "payment_intent_data[metadata][product_id]=prod_premium" \
  -d "payment_intent_data[metadata][product_name]=Premium Plan"
```

##### Subscription (`mode=subscription`)

```bash
curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_live_YOUR_SECRET_KEY: \
  -d "mode=subscription" \
  -d "success_url=https://example.com/success" \
  -d "cancel_url=https://example.com/cancel" \
  -d "line_items[0][price]=price_monthly_premium" \
  -d "line_items[0][quantity]=1" \
  -d "subscription_data[metadata][journey_uuids]=bfab4bc0-b0a5-414b-befc-4aaddc429b0e" \
  -d "subscription_data[metadata][user_id]=user_12345" \
  -d "subscription_data[metadata][device_id]=hwid_abc123" \
  -d "subscription_data[metadata][product_name]=Monthly Premium"
```

## View data

After successful integration, a new **Finance Overview** dashboard appears in the [Dashboards](/product/statistics-and-analytics/dashboards/) section. There you can view Gross Revenue and New Subscriptions statistics broken down by campaigns (journey).

![Finance Overview dashboard in Statistics with Gross Revenue and New Subscriptions by campaign](/integrations-stripe-integration-6.webp)

For more detailed information, visit your Stripe Dashboard.

## Create segments based on payments

Use Stripe events to create user segments:

1. Open **Audience** → **Segments**.
2. Click **Create Segment** → **Build Segment**.
3. In **Add filter by**, click **Event**.
4. Select a Stripe event from the dropdown (see the table below for available events). 
<Aside type="note">
Stripe events appear in the list after the integration is connected and payment data is received. 
</Aside> 

5. Set the condition: how many times the event occurred and the time frame (e.g. during the last 30 days, between dates).
6. Optionally narrow the segment by event attributes. The table below lists the attributes available for each event.

| Event | Description | Attributes |
|-------|-------------|------------|
| `StripePaymentSucceeded` | Successful payment | __amount, __currency, invoice_id, journey_uuids, product_id, product_name, stripe_customer_id, subscription_id |
| `StripeInvoicePaid` | Subscription invoice paid | __amount, __currency, journey_uuids, product_id, product_name, stripe_customer_id, transaction_id, transaction_type |
| `StripeSubscriptionCreated` | Subscription created | __amount, __currency, interval, journey_uuids, product_id, product_name, status, stripe_customer_id, subscription_id |

![Audience Segments page with Create Segment and Build Segment options](/integrations-stripe-integration-7.webp)

7. To add more events, add another Event filter and choose an operator (AND or OR) between conditions.

[Learn more about creating segments](/product/audience-data-and-segmentation/segmentation/create-segments/by-events/).

<Aside type="tip">
You can also map `StripePaymentSucceeded` (`__amount`, `__currency`, `product_id`) or `StripeInvoicePaid` (`__amount`, `__currency`, `transaction_id`, `product_id`) as a source for [Conversion events](/product/audience-data-and-segmentation/events/conversion-events/), to bring Stripe revenue into RFM segmentation, journey attribution, and ManyMoney AI alongside your other revenue sources.
</Aside>

## ManyMoney AI Assistant

After successful Stripe integration, the [**ManyMoney**](/product/pushwoosh-ai/ai-assistant/) AI assistant automatically gains access to payment and subscription statistics.

ManyMoney is available in the Dashboard interface. After you connect Stripe, payment data is available for analysis automatically. No additional configuration is required.

### What ManyMoney can do

- **Analyze revenue:** answers questions about income, conversions, and campaign effectiveness.
- **Compare periods:** shows payment and subscription dynamics across different time intervals.
- **Identify trends:** detects growing and declining products and audience segments.
- **Provide recommendations:** suggests optimizations based on payment data.

<Aside type="tip" title="Prompt examples">

- What revenue did the campaign generate last month?
- Compare subscription conversion rates between January and February
- Show refund statistics

</Aside>