Zeus 对接文档

外观

Stripe ​

一、资料准备 ​

产品方（研发）提供以下内容，后续用于支付校验

项目项目别名描述示例
Webhook 密钥Webhook Secret查看获取步骤whsec_xxx
私钥Secret Key查看获取步骤sk_xx

二、业务时序图 ​

deepseek_mermaid_20260708_10b4e2.png

三、产品技术支持 ​

创建 Checkout Session 时，按支付类型填充 metadata 写到对应对象上。

json
{
    "adjust_id": "adjust_adid_xxx",
    "app_id": 9999 // zeus app id
}

3.1 一次性支付 ​

必须开启 invoice_creation ，否则无法正常追踪，开启代码： invoice_creation.enabled = true

在以下位置填充 adjust id 相关的 metadata

  • Checkout Session 自身 的 metadata
  • payment_intent_data 的 metadata
  • invoice_creation.invoice_data 的 metadata

参数示例

json
metadata.adjust_id = adjust_id_xxx
metadata.app_id = 9999 // zeus app id
payment_intent_data.metadata.adjust_id = adjust_id_xxx
payment_intent_data.metadata.app_id = 9999 // zeus app id
invoice_creation.enabled = true
invoice_creation.invoice_data.metadata.adjust_id = adjust_id_xxx
invoice_creation.invoice_data.metadata.app_id = 9999 // zeus app id

伪代码

javascript
stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  metadata: {
    adjust_id: 'adjust_id_xxx',
    app_id: 9999 // 替换为真实的app id
  },
  payment_intent_data: {
    metadata: {
      adjust_id: 'adjust_id_xxx',
      app_id: 9999 // 替换为真实的app id
    },
  },
  invoice_creation: {
    enabled: true,
    invoice_data: {
      metadata: {
        adjust_id: 'adjust_id_xxx',
        app_id: 9999 // 替换为真实的app id
      },
    },
  },
})

3.2 订阅支付 ​

适用于：普通订阅、付款订阅、带试用订阅，在以下位置填充 adjust id 相关的 metadata

  • Checkout Session 自身 的 metadata
  • subscription_data 的 metadata

示例参数

json
metadata.adjust_id = adjust_id_xxx
metadata.app_id = 9999 // 替换为真实的app id
subscription_data.metadata.adjust_id = adjust_id_xxx
subscription_data.metadata.app_id =  9999 // 替换为真实的app id

伪代码

javascript
stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  metadata: {
    adjust_id: 'adjust_id_xxx',
    app_id: 9999 // 替换为真实的app id
  },
  subscription_data: {
    metadata: {
      adjust_id: 'adjust_id_xxx',
      app_id: 9999 // 替换为真实的app id
    },
  },
})

需要注意的是，如果订阅商品支持试用： 还需要在 subscription_data 中额外追加 trial_period_days

javascript
subscription_data: {
  trial_period_days: 1,
  metadata: {
    adjust_id: 'adjust_id_xxx',
    app_id: 9999 // 替换为真实的app id
  },
}

3.3 退款 ​

退款也需要在metadata 中 传入 app_id

示例参数

json
metadata.app_id = 9999 // 替换为真实的app id

伪代码

javascript
const params = {
   metadata: { app_id: 9999 },
}
if (paymentIntentId) params.payment_intent = paymentIntentId
if (chargeId) params.charge = chargeId
if (amount != null && amount > 0) params.amount = Math.round(Number(amount))

const refund = await stripe.refunds.create(params)

四、接口对接 ​

4.1、域名环境 ​

正式域名：https://sdkapi.zeusai.dev

测试域名：https://sdkapi-sandbox.zeusai.dev

对接期间建议先用测试环境测试，便于双方排查问题

4.2、客户端上报接口 ​

调用时机见时序图步骤 2️⃣

接口URL：/api/s2s/v1/partner/order/stripe

请求方式：POST

请求参数：

参数名类型必填说明示例
app_idInt是发行应用ID（我方提供）10001
adjust_idString是第三方adjust的 adid"1e873a4a-7a1b-4453-9274..."
receipt_dataString是组装支付信息"{}"

返回参数：

参数名类型说明
codeInthttp status = 200 且 code = 0 为成功状态
messageString成功或错误信息

注意事项

  • Receipt Data 需按以下格式组装，示例如下
json
{
  "appId": 10001, // 请替换为正确的AppID
  "productID": "prod_xxx", // 商品ID
  "priceID": "price_xx", // 价格ID
  "invoiceId": "in_xxx",
  "subscriptionId": "sub_xxx", // 订阅商品必传，一次性商品传空
  "sessionId": "nochajllnojjbangbonjedhc.AO-J1OxL..."
}
  • 网络超时情况下，需至少重试1次

4.3、Webhook通知设置 ​

  • 方式一：产品方（研发）服务端转发到我方回传地址的方式，贵芳需要增加指数退避策略进行重试，避免网络抖动带来的数据丢失
  • 方式二：直接在开发者后台填写我方回传地址

需要转发或勾选的事件：

image.png

建议采用方式二

接口兼容

接口URL（旧）：/api/callback/v1/stripe/{app_id}/notification

请求方式：POST

请求参数：通知的原始内容，包括 Header和 Body

接口URL（新）：/api/callback/v1/stripe/notification

请求方式：POST

请求参数：通知的原始内容，包括 Header和 Body