收入
手动付款接口
从后端向 Talivia 发送自定义付款事件。
如果收入来自自定义结账、银行转账、数字货币处理商、应用商店、账单系统或 Talivia 尚未直接连接的其他服务商，请使用手动付款接口。
创建接口密钥
打开网站设置 → 接口密钥并生成密钥。Talivia 会为当前网站创建密钥。
密钥只显示一次，请立即复制。只能将它保存在后端，切勿暴露在浏览器代码中。
发送付款
后端确认已经收到款项后，再把付款事件发送给 Talivia。
结账前，将 window.talivia.getSessionId() 发送给后端，并作为 sessionId 与订单一起保存。
await fetch('https://talivia.com/api/payments/manual', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-talivia-api-key': process.env.TALIVIA_API_KEY,
},
body: JSON.stringify({
websiteId: 'YOUR_WEBSITE_ID',
transactionId: 'order_123',
amount: 49,
currency: 'USD',
providerName: 'manual',
providerPaymentId: 'payment_123',
providerCustomerId: 'customer_123',
sessionId: order.sessionId,
}),
});请使用稳定的编号。
transactionId 应是系统中该笔付款的唯一编号。请求重试时请重复使用同一个编号。支持的归因字段
请尽可能发送会话字段：
sessionIdproviderCustomerIdexternalCustomerIdemailemailHash
Talivia 使用 sessionId 将付款关联到准确的访客路径。首次付款匹配成功后，客户字段可以进一步关联后续续费。
订阅付款与续费
订阅付款支持以下可选字段：
| 字段 | 类型 | 含义 |
|---|---|---|
providerSubscriptionId | string | 账单系统中固定的订阅编号。 |
isRenewal | boolean | 首次付款为 false，续费为 true。请使用 JSON 布尔值。 |
occurredAt | ISO 日期字符串 | 实际收到款项的时间，默认使用请求时间。 |
每笔扣款应使用新的 transactionId，只有重试同一笔扣款时才重复使用。续费时保持 providerName、providerSubscriptionId 和 providerCustomerId 不变，不需要新的浏览器访问或 sessionId。
{
"websiteId": "YOUR_WEBSITE_ID",
"transactionId": "annual_charge_2026",
"providerName": "custom_billing",
"providerSubscriptionId": "subscription_123",
"providerCustomerId": "customer_123",
"amount": 360,
"currency": "USD",
"isRenewal": true,
"occurredAt": "2026-10-19T10:00:00Z"
}这会在收款日期记录完整的 360 美元，不会分摊到订阅的其他月份。如果省略 isRenewal，Talivia 会查找相同服务商与订阅编号的更早付款。若首次付款早于 Talivia 保存的历史记录，请明确发送此标记。
验证
- 从后端发送一笔测试付款。
- 打开该网站的 Talivia 付款列表。
- 确认金额、币种、服务商名称和交易编号。
- 打开访客资料，确认消费金额显示在匹配的访客路径中。