# Stripe 集成

<Aside type="caution" icon="setting" title="需要开发者协助">
在创建 Stripe Checkout Sessions 时，您将需要开发团队的帮助来传递元数据（Journey、用户、设备）。请与他们分享本指南。
</Aside>

[Stripe](https://stripe.com/) 是一个支付平台，可让您接受付款和管理订阅。将 Stripe 与 Pushwoosh 集成后，您可以在[营销活动](/zh/product/customer-journey/pushwoosh-journey-overview/)中跟踪付款和订阅，按 Journey 和产品分析收入，根据付款事件对[用户进行分群](/zh/product/audience-data-and-segmentation/segmentation/)，并使用 [ManyMoney AI](/zh/product/pushwoosh-ai/ai-assistant/) 获取收入洞察。

## 集成概述

### 集成类型

**来源：** 付款和订阅事件从 Stripe 发送到 Pushwoosh。

### 先决条件

要设置 Stripe 与 Pushwoosh 的集成，请确保满足以下条件：

* 您拥有一个有效的 Pushwoosh 账户。
* 您拥有一个 Stripe 账户。

### 术语表（如果实体名称不同，则进行映射）

下表显示了 Stripe 实体如何映射到 Pushwoosh。此映射通过在创建 Checkout Session 时传递相应字段作为元数据来实现（请参阅[元数据配置](#metadata-configuration)）。

| Stripe | Pushwoosh |
|--------|-----------|
| 客户 | 元数据中的 `user_id`（必需），`device_id`（可选） |
| 付款 / 费用 | 事件 **StripePaymentSucceeded** (`charge.succeeded`) |
| 发票（已支付） | 事件 **StripeInvoicePaid** (`invoice.paid`) |
| 订阅 | **StripeSubscriptionCreated** + **StripeInvoicePaid** 中的属性 |
| 产品 / 价格 | 元数据和事件属性中的 `product_id`、`product_name` |
| 营销活动 (Journey) | 元数据中的 `journey_uuids` |

### 同步的实体

* 付款事件（一次性付款、订阅发票）
* 订阅事件（订阅已创建、订阅发票已支付）

### 集成如何工作？

通过 **Stripe Connect** 将您的 Stripe 账户连接到 Pushwoosh 后，Pushwoosh 会从 Stripe 接收付款和订阅数据。您可以通过在创建 Checkout Session 时传递元数据，将每笔交易与营销活动、用户或设备关联起来（请参阅[元数据配置](#metadata-configuration)）。

Pushwoosh 会创建事件，您可以使用这些事件进行[分群](/zh/product/audience-data-and-segmentation/segmentation/)和分析。

##### 数据流

1. 您通过 **Settings** → **3rd-party integrations** 中的 **Stripe Connect** 将您的 Stripe 账户一次性连接到 Pushwoosh。
2. 创建 Checkout Session 时，您传递元数据，以便稍后可以归因付款（请参阅[元数据配置](#metadata-configuration)）。
3. 当 Stripe 中发生付款或订阅事件时（例如，一次性付款的 `charge.succeeded`，订阅的 `invoice.paid`），Stripe 会将数据发送到 Pushwoosh。
4. Pushwoosh 创建相应的事件，并使用元数据进行归因。这些数据会出现在 Finance Overview、Audience → Events 和 ManyMoney 中。

### 用例
##### 跟踪付款
自动接收有关所有成功付款和订阅的信息。

##### 将付款与营销活动关联
通过传递元数据，将交易与特定的[客户旅程](/zh/product/customer-journey/pushwoosh-journey-overview/)关联起来（请参阅[元数据配置](#metadata-configuration)）。

##### 分析收入
按营销活动、产品、用户和设备查看收入。

##### 对您的受众进行分群
基于付款事件[创建分群](/zh/product/audience-data-and-segmentation/segmentation/create-segments/by-events/)。

##### AI 分析
[ManyMoney AI](/zh/product/pushwoosh-ai/ai-assistant/) 助手会自动接收付款和订阅统计数据，并可以基于这些数据做出决策。

## 设置集成

### 将 Stripe 连接到 Pushwoosh

1. 打开任何 Pushwoosh 应用程序（Stripe 账户与您的整个账户关联，而非特定应用程序），然后导航到 **Settings** → **3rd-party integrations**。
2. 找到 **Stripe** 卡片，然后单击 **LOGIN PAGE** 按钮。

![设置页面，其中包含第三方集成部分和带有 LOGIN PAGE 按钮的 Stripe 卡片](/integrations-stripe-integration-1.webp)

3. 您将被重定向到 Stripe 授权页面。

![Stripe 授权页面，其中包含账户选择和 Connect 按钮](/integrations-stripe-integration-2.webp)

4. 在 Stripe 页面上，输入您的电子邮件，然后单击 **Continue**。
5. 登录您的 Stripe 账户（或创建一个新账户）。如果您有多个账户，请选择要连接的账户。
6. 单击 **Connect** 进行确认。
7. 成功授权后，您将被重定向回 Pushwoosh。集成状态将变为 **Connected**。

![第三方集成页面，显示 Stripe 卡片的已连接状态](/integrations-stripe-integration-3.webp)

### 断开集成

##### 方法 1：通过 Pushwoosh

1. 前往 **Settings** → **3rd-party integrations**。
2. 找到 **Stripe** 卡片，然后单击 **SETTINGS** 按钮。
3. 在弹出的窗口中，单击 **Disconnect** 按钮。

![第三方集成中带有 Disconnect 按钮的 Stripe 卡片设置弹窗](/integrations-stripe-integration-4.webp)

##### 方法 2：通过 Stripe Dashboard

1. 登录 [Stripe Dashboard](https://dashboard.stripe.com)。
2. 前往 **Settings** → **Team and security** → **Installed apps**。
3. 在 **Connect Extensions** 部分找到该应用程序。

![Stripe Dashboard 设置、团队与安全、已安装应用、Connect 扩展部分](/integrations-stripe-integration-5.webp)

当您通过 Stripe 断开连接时，Pushwoosh 会自动收到通知并移除集成。

## 元数据配置

Stripe 会将付款事件发送到 Pushwoosh，但如果没有额外数据，Pushwoosh 无法判断付款属于哪个营销活动或哪个用户。当您在创建 Checkout Session 时传递元数据（营销活动 ID、用户或设备 ID、产品），每笔付款都会归因到正确的 Journey 和用户。

然后，您可以在 Finance Overview 中按营销活动查看收入，按付款人构建分群，并使用具有正确归因的 ManyMoney。

### 可用元数据字段

| 字段 | 描述 | 是否必需 | 示例 |
|-------|-------------|----------|---------|
| `journey_uuids` | 营销活动 (Journey) ID，以分号分隔 | 否 | `bfab4bc0-b0a5-414b-befc-4aaddc429b0e;a2bff710-6b49-44d1-96a7-3232feeca6e9` |
| `user_id` | 用户标识符。事件收集和应用 `device_id` 所必需 | 是 | `user_12345` 或 `email@example.com` |
| `device_id` | 设备硬件 ID (HWID)。 | 否 | `hwid_abc123` |
| `product_id` | 产品 ID | 否 | `prod_premium` |
| `product_name` | 产品名称 | 否 | `Premium Plan` |

<Aside type="caution" title="重要">

- 如果没有 `user_id`，事件将不会被收集，`device_id` 也会被忽略。为了进行全面的分析，还请提供 `journey_uuids` 和 `device_id`。

- `journey_uuids` 是可选的，并且只能通过元数据设置。Stripe 不提供营销活动或 Journey 数据，因此如果您希望将收入归因于某个 Journey，请在创建 Checkout Session 时传递它。

- `product_id` 和 `product_name` 是可选的。Pushwoosh 首先使用元数据。如果元数据中缺少其中任何一个，则在可用时从 Stripe 获取。如果两个来源都没有值，则该字段不会被存储。

</Aside>

### 通过 Checkout Session 传递元数据

元数据在创建 Checkout Session 时根据付款类型进行传递：

| 付款类型 | 参数 | Stripe 事件 |
|--------------|-----------|--------------|
| 一次性付款 (`mode=payment`) | `payment_intent_data[metadata]` | `charge.succeeded` |
| 订阅 (`mode=subscription`) | `subscription_data[metadata]` | `invoice.paid` |

### 处理过程中的元数据优先级

**对于订阅**（`invoice.paid` 事件）：

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

**对于一次性付款**（`charge.succeeded` 事件）：

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

## 通过 Stripe API (curl) 创建 checkout session

##### 一次性付款 (`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"
```

##### 订阅 (`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"
```

## 查看数据

成功集成后，[Dashboards](/zh/product/statistics-and-analytics/dashboards/) 部分会出现一个新的 **Finance Overview** 仪表板。您可以在其中查看按营销活动 (Journey) 细分的总收入和新增订阅统计数据。

![统计信息中的财务概览仪表板，显示按营销活动划分的总收入和新增订阅](/integrations-stripe-integration-6.webp)

有关更详细的信息，请访问您的 Stripe Dashboard。

## 基于付款创建分群

使用 Stripe 事件创建用户分群：

1. 打开 **Audience** → **Segments**。
2. 单击 **Create Segment** → **Build Segment**。
3. 在 **Add filter by** 中，单击 **Event**。
4. 从下拉列表中选择一个 Stripe 事件（可用事件请参见下表）。
<Aside type="note">
Stripe 事件在集成连接并收到付款数据后会出现在列表中。
</Aside>

5. 设置条件：事件发生的次数和时间范围（例如，在过去 30 天内，在日期之间）。
6. （可选）通过事件属性缩小分群范围。下表列出了每个事件可用的属性。

| 事件 | 描述 | 属性 |
|-------|-------------|------------|
| `StripePaymentSucceeded` | 付款成功 | __amount, __currency, invoice_id, journey_uuids, product_id, product_name, stripe_customer_id, subscription_id |
| `StripeInvoicePaid` | 订阅发票已支付 | __amount, __currency, journey_uuids, product_id, product_name, stripe_customer_id, transaction_id, transaction_type |
| `StripeSubscriptionCreated` | 订阅已创建 | __amount, __currency, interval, journey_uuids, product_id, product_name, status, stripe_customer_id, subscription_id |

![受众分群页面，其中包含创建分群和构建分群选项](/integrations-stripe-integration-7.webp)

7. 要添加更多事件，请添加另一个事件过滤器，并在条件之间选择一个运算符（AND 或 OR）。

[了解有关创建分群的更多信息](/zh/product/audience-data-and-segmentation/segmentation/create-segments/by-events/)。

## ManyMoney AI 助手

成功集成 Stripe 后，[**ManyMoney**](/zh/product/pushwoosh-ai/ai-assistant/) AI 助手会自动获得对付款和订阅统计数据的访问权限。

ManyMoney 可在 Dashboard 界面中使用。连接 Stripe 后，付款数据可自动用于分析。无需额外配置。

### ManyMoney 的功能

- **分析收入：** 回答有关收入、转化和营销活动效果的问题。
- **比较周期：** 显示不同时间间隔内的付款和订阅动态。
- **识别趋势：** 检测增长和下降的产品和受众分群。
- **提供建议：** 根据付款数据提出优化建议。

<Aside type="tip" title="提示示例">

- 上个月营销活动产生了多少收入？
- 比较一月和二月的订阅转化率
- 显示退款统计数据

</Aside>