Telegram Stars 接入流程

该 API 用于帮助内容提供商（CP）在平台上注册商品信息、设置支付回调地址，并获取生成的商品 ID。注册商品后，CP 可以通过该平台的支付服务进行商品售卖，并接收支付结果的通知。

一、注册信息

1. 开通渠道方账号

需要后台权限，或提交json与相关开发人员联系
后台入口

获取APIKey等相关信息

2. 注册商品信息

信息示例

{
  "name": "Gold Package", // 商品名
  "description": "Get 100 gold coins for in-game purchases.",  // 商品描述
  "price": 500,  // stars 价格
  "photo_url": "xxx", // 商品icon
  ...
}

响应示例

// 注册成功后生成的商品 ID
{
  "productId": "prod_12345"
}

3. 设置支付成功的回调地址

后台入口 **需要后台权限，或提交json与相关开发人员联系

信息示例

{
  "callbackUrl": "https://cpdomain.com/new/payment/callback"
}

响应示例

{
  "success": true
}

订单字段完整信息请参考: npmjs 最新版本定义

二、SDK集成

嵌入版SDK

参考：嵌入方式（旧）中，pay stars的内容。

NPM版

暂无

三、支付成功回调

功能描述 ：支付成功后，平台将向 CP 提供的回调地址发送支付通知。

请求方式：POST

加密方式：签名加密, X-Signature

回调地址：由 callbackUrl 指定

回调规则：需要返回 { success: boolean; message: string } 格式的对象, 如果success不为true, 则重试发货

回调数据

参数名	类型	描述
`transactionId`	`string`	支付的唯一交易 ID
`orderId`	`string`	我方订单号，用于标识平台内的订单
`items`	`array`	购买的商品列表，包含商品 ID 和数量
`items[].itemId`	`string`	商品的唯一 ID
`items[].quantity`	`number`	商品数量
`amount`	`number`	支付总金额，单位为分
`currency`	`string`	货币代码，例如 "USD" , stars支付为 "XTR"
`timestamp`	`number`	支付完成的时间戳
`payload`	`string`	CP 方传入的扩展信息，例如外部订单号等
`metadata`	`object`	可选的扩展信息，用于传递自定义数据

回调数据示例

headers

"X-Signature": ....signature

body

{
  "transactionId": "txn_67890",
  "orderId": "order_54321",
  "items": [
    {
      "itemId": "item_001",
      "quantity": 2
    },
    {
      "itemId": "item_002",
      "quantity": 1
    }
  ],
  "amount": 1500,
  "currency": "USD",
  "timestamp": 1678923456,
  "payload": "ext_order_78901",
  "metadata": {
    "platform": "apple",
    "region": "US",
    "deviceId": "device_abc123",
    "customData": {
      "extraInfo": "example"
    }
  }
}

四、成功回调后验证签名

1.接收回调内容
收到上述 JSON 数据。

2.提取并重新生成签名
提取 headers 中 X-Signature 字段与 Body 中 Json 对象，按字符顺序规则拼接 baseString，然后使用API密钥生成签名

3.处理回调数据
验签通过后，执行订单处理逻辑。

4.加密注意事项
1.字段顺序：使用Key的字母序排序。
2.签名算法：使用 HMAC-SHA256 加密算法。
3.密钥管理：API密钥需安全存储，不应在代码中明文暴露。
4.Replay 防护：验证 timestamp 是否在合理范围（如 5 分钟内），超时拒绝请求。
5.数据类型处理：确保 JSON 序列化与签名步骤的格式一致。

五、附录

TypeScript 类型定义

验签示例

Telegram Stars 接入流程

一、注册信息#

1. 开通渠道方账号#

2. 注册商品信息#

3. 设置支付成功的回调地址#

二、SDK集成#

嵌入版SDK#

NPM版#

三、支付成功回调#

四、成功回调后验证签名#

五、附录#