Open API / 推送支付密码

推送支付密码

业务触发支付密码，后端生成支付密码发送到 IM 端，IM 收到支付密码后回填，完成后续业务。

RSA2 仅服务端 application/json

POST /v1/system-push/pay-password

签名算法见签名规范。本页只写本接口的 PATH、字段和错误码。

调用时机

业务方需要触发支付密码并向 IM 发送时，由业务方自行判断是否调用。

userNo 必须是平台众享号。已有 IM 映射时直接推送；没有映射时可带 phone，服务会建一个登录密码为空的本地号、导入腾讯云 IM，再推送。不带 phone 且未同步返回 code=404。不要传直播 uid。

签名 PATH

项	值
METHOD	`POST`
HTTP 路径	`/v1/system-push/pay-password`
签名 PATH	`/api/open/v1/system-push/pay-password`
生产 URL	`https://chatlive.openapi.zhengdeyunqi.cn/v1/system-push/pay-password`

请求体

字段	类型		约束	说明
`userNo`	string	必填	最长 32	平台众享号
`payPassword`	string	必填	6 位数字	明文支付密码
`phone`	string	条件	11 位手机号	无 IM 映射时必填。按手机号建本地空密码账号并导入 IM
`nickname`	string	可选	最长 100	新建本地号时的昵称；空则自动生成
`text`	string	可选	最长 3000	正文，可含 `{payPassword}`。默认 `您的支付密码：{payPassword}`
`title`	string	可选	最长 200	离线通知标题。默认 `支付密码`

json

{
  "userNo": "69493154",
  "payPassword": "847291",
  "phone": "13800138000"
}

响应

统一信封。以 code 为准：鉴权失败多为 HTTP 4xx；业务失败多为 HTTP 200 且 code != 0。

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "imUserId": "42",
    "c2cDelivered": 1
  }
}

字段	说明
`imUserId`	直播侧 IM 账号
`c2cDelivered`	`1` 表示会话已提交，不表示用户已读

错误码

HTTP	code	message	处理
400	400	缺少必要请求头	补齐 `X-YS-*`
400	400	不支持的签名类型	`X-YS-Sign-Type` 设为 `RSA2`
400	400	时间戳无效	使用 Unix 秒并校准时钟
400	400	密钥版本无效	确认 `v1`
400	400	签名无效	核对待签串与私钥
400	400	nonce 重复	更换 nonce
400	400	参数错误	检查 `userNo` 与 6 位数字密码
403	403	应用无效或未启用	核对 AppID
403	403	接口未授权	联系开通权限
403	403	IP 不在白名单	报备出口 IP
429	429	请求过于频繁	间隔后重试
200	404	用户未同步或映射不存在	先同步，或带 `phone` 让本接口自动建空密码 IM 号
200	4091	手机号已绑定其他众享号	不要改绑，改用原众享号
200	5608	推送失败	按重试策略重试。含 IM 建号失败

重试

结果	是否重试
超时、连接失败、`5608`	是。1s / 2s / 4s，最多 3 次
`429`	是。至少间隔 1 秒
`404` / `400` / `403` / `0`	否

重试须更换 X-YS-Timestamp、X-YS-Nonce，建议更换 X-YS-Request-Id，并对同一份 body 重新签名。同一密码成功推送后不要再推。

调用示例

http

POST /v1/system-push/pay-password HTTP/1.1
Host: chatlive.openapi.zhengdeyunqi.cn
Content-Type: application/json
X-YS-App-Id: ys_app_asset
X-YS-Timestamp: 1756610000
X-YS-Nonce: a1b2c3d4e5f67890
X-YS-Request-Id: req_001
X-YS-Sign-Type: RSA2
X-YS-Key-Version: v1
X-YS-Signature: <RSA2 Base64>

{"userNo":"69493154","payPassword":"847291"}

body, _ := json.Marshal(map[string]string{
    "userNo": "69493154", "payPassword": "847291",
})
ts := strconv.FormatInt(time.Now().Unix(), 10)
nonce := fmt.Sprintf("n_%d", time.Now().UnixNano())
reqID := fmt.Sprintf("req_%d", time.Now().UnixNano())
appID := "ys_app_asset"
sum := sha256.Sum256(body)
canonical := strings.Join([]string{
    "POST",
    "/api/open/v1/system-push/pay-password",
    "",
    appID, ts, nonce, reqID,
    hex.EncodeToString(sum[:]),
}, "\n")
sig := SignRSA2(privateKeyPEM, canonical)

req, _ := http.NewRequest(http.MethodPost, url, bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-YS-App-Id", appID)
req.Header.Set("X-YS-Timestamp", ts)
req.Header.Set("X-YS-Nonce", nonce)
req.Header.Set("X-YS-Request-Id", reqID)
req.Header.Set("X-YS-Sign-Type", "RSA2")
req.Header.Set("X-YS-Key-Version", "v1")
req.Header.Set("X-YS-Signature", sig)