Open API / 推送支付密码

推送支付密码

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

RSA2 仅服务端 application/json

POST /v1/system-push/pay-password

调用时机签名 PATH 请求体响应错误码重试示例

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

调用时机

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

userNo 必须是平台用户编号，且该用户已完成与直播侧的账号同步。未同步返回 code=404。不要传直播 uid 或手机号。

签名 PATH

项	值
METHOD	`POST`
HTTP 路径	`/v1/system-push/pay-password`
签名 PATH	`/api/open/v1/system-push/pay-password`
测试 URL	`https://test-chat-live-open-go.gyyx.store/v1/system-push/pay-password`
生产 URL

请求体

字段	类型		约束	说明
`userNo`	string	必填	最长 32	平台用户编号
`payPassword`	string	必填	6 位数字	明文支付密码
`text`	string	可选	最长 3000	正文，可含 `{payPassword}`。默认 `您的支付密码：{payPassword}`
`title`	string	可选	最长 200	离线通知标题。默认 `支付密码`

json

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

响应

统一信封。以 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	用户未同步或映射不存在	待该 `userNo` 同步完成后再调
200	5608	推送失败	按重试策略重试

重试

结果	是否重试
超时、连接失败、`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: test-chat-live-open-go.gyyx.store
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)