IAP 通用透传事件 (asset.iap.notification) 说明文档

asset.iap.notification 是一个通用的 IAP (In-App Purchase) Webhook 事件，由 BytePower Server 接收到第三方支付平台（Paddle, Stripe, PayPal, FunnelFox）的 Webhook 通知后即时触发。

该事件旨在无损透传第三方平台的原始数据，供下游服务（如数据分析、BI 系统、自定义业务逻辑）使用，而无需关心具体的支付逻辑处理结果。

1. 事件结构 (Event Structure)

所有 asset.iap.notification 事件均遵循统一的 JSON 结构：

字段名	类型	说明
id	String	事件唯一 ID (Snowflake ID)
time	Integer	事件发生时间 (毫秒时间戳)
name	String	固定为 asset.iap.notification
user_id	String	BytePower 用户 ID (如果能关联到)
app_id	String	BytePower 应用 ID
platform	String	支付平台 (paddle, stripe, paypal, funnelfox)
app_platform	String	应用平台 (ios, android, web 等) - 取自 AppConfig
bundle_id	String	Bundle ID - 取自 AppConfig
bytepower_product_id	String	BytePower 产品 ID (关联到的内部产品)
platform_product_id	String	平台产品 ID (如 Stripe Price ID)
client_ip	String	客户端 IP (如果可用)
environment	String	环境 (develop, debug 或 product)
api_env	String	API 环境 (production, sandbox)
device_info	Object	设备信息对象 (包含 device_id, idfa, idfv 等)
data	Object	核心负载数据 (包含平台原始信息)

{
  "id": "snowflake_id",        // 事件唯一 ID
  "time": 1678886400000,       // 事件发生时间 (毫秒时间戳)
  "name": "asset.iap.notification",
  "user_id": "user_123",       // 用户 ID (如果能关联到)
  "app_id": "app_abc",         // 应用 ID
  "platform": "paddle",        // 支付平台 (paddle, stripe, paypal, funnelfox)
  "app_platform": "ios",       // 应用平台 (ios, android, web, etc.) - 取自 AppConfig
  "bundle_id": "com.example.app", // Bundle ID - 取自 AppConfig
  "bytepower_product_id": "bp_prod_1", // BytePower 产品 ID (关联到的内部产品)
  "platform_product_id": "p_123",      // 平台产品 ID (如 Stripe Price ID)
  "client_ip": "1.2.3.4",      // 客户端 IP (如果可用)
  "environment": "production", // 环境 (develop, debug 或 product)
  "api_env": "production",     // API 环境 (production, sandbox)
  "device_info": {             // 设备信息 (如果关联到了购买时的设备信息)
    "device_id": "...",
    "idfa": "...",
    "idfv": "..."
  },
  "data": {                    // **核心负载数据** (包含平台原始信息)
    // 各平台特定的数据字段，详见下文
  }
}

2. Platform Specific Data Payload

data 字段中的内容根据 platform 的不同而有所差异。以下是各平台的数据结构说明。

2.1 Common Data Fields

所有平台的 data 对象中都包含以下通用字段：

字段名	类型	说明
platform_event_type	String	平台特定的事件类型字符串 (e.g., transaction.completed, PAYMENT.SALE.COMPLETED).

2.2 Paddle

当 platform 为 paddle 时，data 包含以下字段：

字段名	类型	说明
paddle_event	Object	[核心] Paddle 原始事件对象 (完整结构)
paddle_subscription	Object	(可选) Paddle 订阅详情对象。当事件涉及订阅时存在。
paddle_transaction	Object	(可选) Paddle 交易详情对象。当事件涉及交易时存在。
paddle_adjustment	Object	(可选) Paddle 调整(Refund/Chargeback)对象。

示例 Data:

"data": {
  "paddle_event": {
    "event_id": "evt_...",
    "event_type": "transaction.completed",
    "data": { ... } // 原始 payload
  },
  "paddle_transaction": {
    "id": "txn_...",
    "status": "completed",
    ...
  },
  "paddle_subscription": {
    "id": "sub_...",
    "status": "active",
    ...
  }
}

2.3 Stripe

当 platform 为 stripe 时，data 包含以下字段：

字段名	类型	说明
stripe_event	Object	[核心] Stripe 原始 Event 对象 (完整结构)
stripe_subscription	Object	(可选) Stripe Subscription 对象。
stripe_invoice	Object	(可选) Stripe Invoice 对象。当事件为 Invoice 相关时存在。
stripe_payment_intent	Object	(可选) Stripe PaymentIntent 对象。
stripe_refund	Object	(可选) Stripe Refund 对象。

示例 Data:

"data": {
  "stripe_event": {
    "id": "evt_...",
    "type": "invoice.payment_succeeded",
    "data": {
      "object": { ... } // Invoice object
    }
  },
  "stripe_invoice": { ... },
  "stripe_subscription": { ... }
}

2.4 PayPal

当 platform 为 paypal 时，data 包含以下字段：

字段名	类型	说明
paypal_event	Object	[核心] PayPal 原始 Webhook 事件对象
paypal_subscription	Object	(可选) PayPal 订阅详情对象。
paypal_order	Object	(可选) PayPal 订单/交易对象 (Sale 或 Capture)。
paypal_refund	Object	(可选) PayPal 退款对象。

示例 Data:

"data": {
  "paypal_event": {
    "id": "WH-...",
    "event_type": "PAYMENT.SALE.COMPLETED",
    "resource_type": "sale",
    "resource": { ... }
  },
  "paypal_order": { ... }, // Sale object
  "paypal_subscription": { ... }
}

2.5 FunnelFox

当 platform 为 funnelfox 时，data 包含以下字段：

字段名	类型	说明
funnelfox_event	Object	[核心] FunnelFox 原始事件对象 (完整结构)

注意: FunnelFox 的事件对象内部已经包含了 Subscription, Order, User 等详细信息，因此通常直接读取 funnelfox_event 即可。

示例 Data:

"data": {
  "funnelfox_event": {
    "event_id": "...",
    "event_type": "subscription",
    "subtype": "renewing",
    "subscription": { ... },
    "order": { ... },
    "user": { ... }
  }
}

3. 开发指南

3.1 消费 data 字段

由于 data 是一个 map[string]any，建议开发者首先根据外层的 platform 字段判断来源，然后直接读取对应的 *_event 核心字段（如 paddle_event, stripe_event 等）。这些字段包含了最完整、最原始的 Webhook 数据。

其他辅助字段（如 paddle_subscription）是为了方便快速访问而提取的，可能需要进行空值检查。

3.2 字段关联

BytePower Server 会尝试根据 Webhook 数据关联内部用户和产品：

• user_id: 如果 Webhook 数据中包含透传的 BytePower 用户 ID，或者能通过 Subscription ID 在内部数据库找到对应记录，则会自动填充。
• bytepower_product_id: 关联到的 BytePower 内部产品 ID。

如果这些字段为空，说明该 Webhook 事件可能来自未知用户或无法关联的交易（例如未在 BytePower 系统中初始化的外部购买）。