抖音虚拟支付/小游戏支付端口回调-SKILL
109 浏览2026年09月20日作者:aloxing

小游戏支付端原文档地址

SKILL.md

---
name: bytedance-minigame-pay-callback
description: Implement, configure, and troubleshoot ByteDance/Douyin mini-game virtual-payment (虚拟支付) server-side callbacks in any backend language. Covers GET echostr URL verification, POST payment notification, the SHA1 signature over sorted [token,timestamp,nonce,msg], order fields (appid/cp_orderno/order_no_channel/amount_cent/amount_coin/currency), HTTP-200 vs retry semantics, idempotent delivery and anti-loss persistence, with a complete Go reference implementation. Critically documents that the callback URL MUST be an ICP-filed HTTPS domain with a valid non-expired certificate, no IP, no localhost and no port, otherwise the platform can never reach it. Use when integrating or debugging 字节/抖音小游戏虚拟支付回调, bytedance pay callback, /v1/api/pay/callback, echostr 验证, 支付回调验签, or 支付回调收不到/验证不通过.
---

# 字节 / 抖音小游戏虚拟支付回调(任意后端实现指南)

在任意后端语言中实现字节小游戏「虚拟支付」服务端回调:**GET 可访问性验证** + **POST 支付通知**,含签名算法、订单结构、重试语义、防丢单,并附一套完整 Go 参考实现(见 [reference-go-implementation.md](reference-go-implementation.md))。

## 何时使用

- 接入或排查 字节 / 抖音小游戏虚拟支付服务端回调
- 后台配置回调地址时「验证不通过」,或支付成功后「收不到回调」
- 需要实现 echostr 验证、SHA1 验签、订单落库与发货

---

## ⚠️ 头号铁律:回调地址必须是「已备案 + 证书有效的 HTTPS 域名」

**这是最容易踩、且一旦踩了平台就完全调不到你的坑。** 字节平台对回调「服务器地址」有硬性要求(来源:抖音开放平台官方文档):

| 要求 | 说明 |
|---|---|
| ✅ 必须是域名 | 不能是 IP 地址、不能是 localhost |
| ✅ 必须 HTTPS | http 不被接受 |
| ✅ **证书必须有效、未过期** | 证书过期 / 域名不匹配 / 证书链不完整 → 平台 TLS 握手失败,回调根本发不出 |
| ✅ 必须 ICP 备案 | 未备案域名无法通过验证 |
| ✅ 不能带端口号 | `https://a.com:8443` 非法,只能用默认 **443** |

### 为什么「用 IP 本地自测能通」具有欺骗性

手动 `curl -k https://<你的服务器IP>:<端口>/v1/api/pay/callback` 返回 `success`,只证明你的**代码逻辑正确**(`-k` 还跳过了证书校验);但字节**平台服务端**回调时用的是你在后台填写的地址,且会**严格校验 HTTPS 证书**。若填的是 **IP / 带端口 / 未备案域名 / 证书过期**,平台要么**保存时验证不通过**,要么**根本发不出请求** → 你**永远收不到真实支付回调**。

> 一句话:`IP:端口 + 自签证书` 自测通过 ≠ 平台能调到。上线前必须换成「备案域名 + 443 + 有效证书」。

### 证书必须未过期(重点补充)

平台是通过 HTTPS **主动连接**你的回调地址的,证书一旦有问题,连 GET 可访问性验证都过不了:

- **过期**:证书 `notAfter` 已过 → 握手失败。上线前查、并配**自动续期**。
- **域名不匹配**:证书 CN/SAN 与回调域名不一致 → 握手失败。
- **证书链不完整**:只部署了站点证书、缺中间证书 → 部分客户端(含平台)握手失败,但浏览器可能因缓存而"看起来正常"。务必部署 **fullchain**。

自检命令:
```bash
# 查看证书有效期与颁发对象
echo | openssl s_client -connect pay.example.com:443 -servername pay.example.com 2>/dev/null \
  | openssl x509 -noout -dates -subject -issuer
```

### 正确落地步骤

1. 备案域名(如 `pay.example.com`)解析到服务器公网 IP
2. 为该域名签发 HTTPS 证书,**部署 fullchain 并配置到期自动续期**(Let's Encrypt certbot / 云厂商)
3. 后端可继续监听内部端口(如 8080),用 Nginx/Caddy 把 **443 反代到 8080**(对外不带端口)
4. 回调地址填:`https://pay.example.com/v1/api/pay/callback`
5. 到「开发者平台 → 商业化 → 虚拟支付 → 支付设置」填 **服务器地址** + **服务器回调 Token**,平台发 GET 验证通过后才生效

Nginx 反代示例(443 → 8080):
```nginx
server {
    listen 443 ssl;
    server_name pay.example.com;
    ssl_certificate     /etc/ssl/pay.example.com.fullchain.pem;  # 必须含中间证书
    ssl_certificate_key /etc/ssl/pay.example.com.key;
    location /v1/api/pay/callback {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

| ❌ 错误回调地址 / 配置 | ✅ 正确 |
|---|---|
| `https://<你的服务器IP>:<端口>/...`(IP+端口) | `https://pay.example.com/v1/api/pay/callback` |
| `http://pay.example.com/...`(非 HTTPS) | `https://pay.example.com/...` |
| `https://pay.example.com:8443/...`(带端口) | 443 省略端口 |
| 证书已过期 / 自签 / 缺中间证书 | 有效 CA 证书 + fullchain + 自动续期 |

---

## 回调流程(两个接口,同一地址)

平台对同一个回调地址用 **GET / POST 两种方法**,逻辑不同:

1. **GET —— 接口可访问性验证**:平台配置地址时发起,query 带 `timestamp / nonce / msg / signature / echostr`。你验签通过后**原样回显 `echostr`**(纯文本),验证通过配置才生效。
2. **POST —— 支付成功通知**:玩家支付成功后平台推送订单,body 为 JSON `{timestamp, nonce, msg, signature}`,其中 **`msg` 是一段 JSON 字符串,需二次解析**成订单信息。处理成功返回 **HTTP 200**。

> 支付失败不会回调;客户端 SDK 的支付回调**不能**作为发货依据,**必须以服务端 POST 回调为准**。

---

## 签名算法(语言无关)

GET 与 POST 用**同一套**验签算法:

```
1. 取四个字符串:token, timestamp, nonce, msg
   - token 为后台配置的「服务器回调 Token」
   - msg 在 GET 验证阶段通常为空串;POST 阶段为订单 JSON 字符串
2. 把这 4 个字符串放进数组,按【字节字典序】升序排序(ordinal / bytewise,不是本地化排序)
3. 直接拼接(无分隔符)成一个字符串 s
4. signature = lowercase( hex( SHA1( s ) ) )
5. 与请求携带的 signature 比较(建议大小写不敏感)
```

**关键注意**:
- 排序必须是**字节序**(Go `sort.Strings`、Java `String.compareTo`、C `strcmp`、JS 默认 `Array.sort()` 对纯 ASCII 均可;但 .NET 要用 `StringComparer.Ordinal`,不要用文化敏感排序)。
- `msg` 为空时,加不加空串结果一致(空串排序在最前、拼接贡献为空)。
- 输出是 **SHA1 的十六进制小写**,不是 base64。

伪代码:
```text
arr = [token, timestamp, nonce, msg]
sort_ascending_bytewise(arr)
sig = sha1_hex_lower(join(arr, ""))
return sig == request.signature   // 大小写不敏感
```

---

## POST 订单数据结构

外层 body:

| 字段 | 类型 | 说明 |
|---|---|---|
| `timestamp` | string | 时间戳 |
| `nonce` | string | 随机串 |
| `msg` | string | **订单 JSON 字符串**,需二次解析 |
| `signature` | string | 对 `[token,timestamp,nonce,msg]` 的签名 |

`msg` 二次解析后(`OrderSuccessPayInfo`):

| 字段 | JSON key | 类型 | 说明 |
|---|---|---|---|
| Appid | `appid` | string | 小游戏 appid,用于校验订单归属 |
| CpOrderNo | `cp_orderno` | string | 开发者自定义订单号(**基础库 1.55.0+ 才有**) |
| CpExtra | `cp_extra` | string | 开发者透传参数(**1.55.0+ 才有**) |
| OrderNoChannel | `order_no_channel` | string | 官方交易单号(**总是存在,对账主键**) |
| AmountCent | `amount_cent` | int64 | 订单金额,单位**分** |
| AmountCoin | `amount_coin` | int64 | 购买的游戏币数量 |
| Currency | `currency` | string | `CNY` 人民币 / `DIAMOND` 钻石 |

---

## 返回码与重试语义

- 平台判定成败**只看 HTTP 状态码**:`200` = 成功、不再重试;**非 200** = 失败,按 `10s/30s/1m/2m/…/2h` 重试,**总计约 4 小时 45 分**。
- 因此返回码策略要围绕「**合法订单绝不静默丢失**」:

| 情况 | 建议返回 | 理由 |
|---|---|---|
| 处理成功(含幂等重复) | 200 | 停止重试 |
| body/msg 解析失败、验签失败、落库失败 | 非 200(如 400/401/500) | 触发重试,等修复后补单 |
| appid 不匹配(非本游戏订单) | 200 + 留痕 | 重试无意义,但要记录 |

- **幂等**:平台会重试,同一订单可能多次到达,必须按 `order_no_channel`(回退 `cp_orderno`)**去重**,只发货一次。

---

## 防丢单最佳实践(P0–P3,摘要)

核心原则:**到达即留痕,绝不静默丢弃**。详见 [reference-go-implementation.md](reference-go-implementation.md)。

- **P0 入口无条件存原始报文**:进 handler 第一行就把原始 body + query + headers + IP + 时间追加写入 append-only 日志,**不验签/不解析/不去重**。后续任何一步失败都能事后补单。
- **P1 失败/不匹配也留痕**:appid 不匹配、验签失败等,结构化数据存不下也要靠 P0 原始日志兜底。
- **P2 双写冗余**:本地文件 + MySQL/OSS,防单机磁盘故障。
- **P3 主动对账**:定时从字节后台「商业化 → 虚拟支付 → 支付指标明细」拉官方交易单号与本地比对补漏——这是唯一能覆盖「请求根本没到达(宕机/网络/证书过期)」的防线。

---

## 任意后端实现清单

```
- [ ] 回调地址是「已备案 HTTPS 域名、不带端口」,并已 443 反代到后端
- [ ] HTTPS 证书有效未过期、域名匹配、部署 fullchain、已配自动续期
- [ ] GET 处理:验签通过原样回显 echostr(纯文本 200);失败返回空串
- [ ] POST 处理:验签 -> 二次解析 msg -> 校验 appid -> 幂等 -> 发货 -> 200
- [ ] 验签用「字节序排序 + SHA1 + hex 小写」,msg 参与排序
- [ ] 返回码策略:成功 200;可恢复失败非 200 触发重试
- [ ] 幂等去重键 = order_no_channel(回退 cp_orderno)
- [ ] P0:入口无条件落盘原始报文
- [ ] 订单持久化(文件/DB),并规划 P3 主动对账
- [ ] 不以客户端 SDK 回调作为发货依据
```

---

## 测试方法

- **本地/内网自测**(验证代码逻辑):可用 IP:端口 直接构造带签名的 GET/POST 请求打自己的服务,确认 echostr 回显、验签、落盘、返回码都对。参考实现附带 PowerShell 测试脚本,签名逻辑与后端严格一致。
- **平台联调**(验证真能被调到):**必须**先把地址换成「备案域名 + 443 + 有效证书」,在后台「支付设置」通过 GET 验证,再用真实/沙箱支付触发 POST。
- 自测通过但平台调不到 → 99% 是**域名/备案/端口/HTTPS/证书过期**问题,回到本文头号铁律排查。

---

## 常见坑速查

| 现象 | 根因 | 解决 |
|---|---|---|
| 后台保存回调地址就「验证失败」 | IP / 带端口 / 未备案 / 非 HTTPS / 证书无效 / GET 未回显 echostr | 换备案域名 443 + 有效证书,GET 原样回 echostr |
| 自测能通、平台支付后收不到 POST | 回调地址不是合规域名,平台没发 | 用备案域名 |
| 浏览器能访问、平台却调不到 | **证书过期 / 证书链不完整 / 域名不匹配** | 更新证书、部署 fullchain、开启自动续期 |
| 验签总是失败 | 排序用了本地化排序 / msg 没参与 / hex 大小写或用了 base64 | 改字节序排序、msg 入排序、SHA1 hex 小写 |
| 订单重复发货 | 未做幂等,平台重试导致多次处理 | 按 order_no_channel 去重 |
| msg 解析为空 | 忘了 msg 是「JSON 字符串」需二次解析 | 先取外层 msg,再 unmarshal |
| 偶发丢单、查无记录 | 只在校验通过后才存,失败请求被丢弃 | 加 P0 入口原始报文落盘 + P3 对账 |
| `cp_orderno`/`cp_extra` 为空 | 客户端基础库 < 1.55.0 | 以 `order_no_channel` 为准对账 |

---

## 接口文档与参考实现

- **接口文档**(三个回调接口的完整规格:参数 / 响应 / 返回码 / 签名 / 幂等 / 时序 / curl 示例):[api-reference.md](api-reference.md)
- **Go 参考实现**(通用虚拟支付命名、逐文件详解、可复制核心代码、打包部署与测试脚本):[reference-go-implementation.md](reference-go-implementation.md)

reference-go-implementation.md

# Go 参考实现(通用虚拟支付回调)

一套可直接照搬到任意语言的字节虚拟支付回调 Go 参考实现,逐文件说明完整落地。以下命名均为通用「虚拟支付」语义、与任何具体项目无关;仅 HTTP 路径与订单字段沿用字节平台官方规定(改了平台就调不到 / 解析不到)。

## 目录结构与职责

```
internal/paycallback/
├── pay_dto.go               # 数据结构:OrderInfo(外层) / OrderSuccessPayInfo(订单) / DedupKey
├── pay_sign.go              # 验签:VerifyPaySignature(字节序排序 + SHA1 + hex 小写)
├── pay_middleware.go        # PayCallbackGate:回调接口在线启停(查询失败 fail-open)
├── pay_callback_handler.go  # Ping / VerifyPayCallback(GET) / HandlePayNotify(POST) 完整链路
├── pay_order_store.go       # 订单本地 JSON 存储:幂等去重 + 原子写(含 unmatched 留痕)
├── pay_raw_log.go           # 原始报文 append-only 日志(P0 防丢单)
└── *_test.go                # 单测:幂等 / 去重键 / 原始日志并发
```

配置结构 `PayCallbackConfig`,路由在服务入口注册。

---

## 1. 配置

```go
type PayCallbackConfig struct {
    Token          string `yaml:"token"`            // 后台「服务器回调 Token」
    Appid          string `yaml:"appid"`            // 小游戏 appid,配置后校验订单归属
    OrderStorePath string `yaml:"order-store-path"` // 订单本地 JSON 路径
    RawLogPath     string `yaml:"raw-log-path"`     // 原始报文日志路径(P0)
}
```

```yaml
pay-callback:
  token: <YOUR_CALLBACK_TOKEN>   # 后台「服务器回调 Token」,切勿写入代码库/文档
  appid: ""                      # 留空跳过归属校验;填真实 appid 后不匹配走 unmatched 留痕
  order-store-path: "./data/pay_orders.json"
  raw-log-path: "./data/pay_raw.log"
```

路径为相对工作目录,部署时程序须从含配置文件的目录启动。

---

## 2. 路由注册

字节平台官方规定的回调路径(GET/POST 同一地址,靠 HTTP 方法区分):

```go
h := &paycallback.PayCallbackHandler{}
r.GET ("/v1/ping",             paycallback.PayCallbackGate(), h.Ping)
r.GET ("/v1/api/pay/callback", paycallback.PayCallbackGate(), h.VerifyPayCallback) // URL 验证
r.POST("/v1/api/pay/callback", paycallback.PayCallbackGate(), h.HandlePayNotify)   // 支付通知
```

启动时初始化订单存储与原始日志:
```go
paycallback.InitPayOrderStore(cfg.PayCallback.OrderStorePath)
paycallback.InitPayRawLog(cfg.PayCallback.RawLogPath)
```

> GET 与 POST 同一路径、靠方法区分——正是平台「先 GET 验证、后 POST 通知」的要求。

---

## 3. 数据结构(pay_dto.go)

```go
// 外层信封:GET(query) / POST(body) 共用(字段名为字节官方约定)
type OrderInfo struct {
    Timestamp string `json:"timestamp"`
    Nonce     string `json:"nonce"`
    Msg       string `json:"msg"`       // POST 时是订单 JSON 字符串,需二次解析
    Signature string `json:"signature"`
    EchoStr   string `json:"echostr"`   // 仅 GET 验证阶段回显
}

// msg 二次解析后的订单(字节官方 OrderSuccessPayInfo)
type OrderSuccessPayInfo struct {
    Appid          string `json:"appid"`
    CpOrderNo      string `json:"cp_orderno"`       // 基础库 1.55.0+ 才有
    CpExtra        string `json:"cp_extra"`         // 基础库 1.55.0+ 才有
    OrderNoChannel string `json:"order_no_channel"` // 官方交易单号,总是存在
    AmountCent     int64  `json:"amount_cent"`      // 金额,单位分
    AmountCoin     int64  `json:"amount_coin"`      // 游戏币数量
    Currency       string `json:"currency"`         // CNY / DIAMOND
}

// 幂等去重键:优先官方交易单号,回退开发者订单号
func (o OrderSuccessPayInfo) DedupKey() string {
    if o.OrderNoChannel != "" {
        return o.OrderNoChannel
    }
    return o.CpOrderNo
}
```

> `OrderInfo` / `OrderSuccessPayInfo` 及各 `json` 字段名均为**字节官方协议术语**,必须原样保留,否则解析不到平台数据。

---

## 4. 验签(pay_sign.go)

```go
func VerifyPaySignature(token, timestamp, nonce, msg, signature string) bool {
    list := []string{token, timestamp, nonce}
    if msg != "" {
        list = append(list, msg)
    }
    sort.Strings(list)                       // 字节序升序(Go 字符串比较即 ordinal)
    joinStr := strings.Join(list, "")        // 无分隔符拼接
    h := sha1.New()
    h.Write([]byte(joinStr))
    calculated := strings.ToLower(fmt.Sprintf("%x", h.Sum(nil))) // hex 小写
    return strings.EqualFold(calculated, signature)              // 大小写不敏感比较
}
```

**移植要点**:字节序排序(.NET 用 `StringComparer.Ordinal`,勿用文化排序);`msg==""` 时加不加空串结果一致。

---

## 5. 启停中间件(pay_middleware.go)

```go
// PayCallbackGate 按「回调接口配置表」在线启停回调接口
func PayCallbackGate() gin.HandlerFunc {
    return func(c *gin.Context) {
        enabled, err := loadCallbackEnabled(c.FullPath(), c.Request.Method)
        // 仅“明确查到且被禁用”才拦截;查询失败/行缺失时 fail-open,避免误判 403 触发平台重试风暴
        if err == nil && !enabled {
            c.AbortWithStatus(http.StatusForbidden)
            return
        }
        c.Next()
    }
}
```

启停状态存于一张「回调接口配置表」,可在管理后台在线开关,无需重启。

---

## 6. 处理器(pay_callback_handler.go)

### GET —— URL 验证

```go
func (h *PayCallbackHandler) VerifyPayCallback(c *gin.Context) {
    token := config.PayCallback.Token
    if VerifyPaySignature(token, c.Query("timestamp"), c.Query("nonce"), c.Query("msg"), c.Query("signature")) {
        c.String(200, c.Query("echostr")) // 验签通过原样回显 echostr(纯文本)
        return
    }
    c.String(200, "") // 失败返回空串(平台比对 echostr 不匹配即判失败)
}
```

### POST —— 支付通知(完整链路 + P0 + P1)

```go
func (h *PayCallbackHandler) HandlePayNotify(c *gin.Context) {
    // P0:任何校验之前,无条件把原始报文追加落盘(到达即留痕)
    rawBody, _ := io.ReadAll(c.Request.Body)
    c.Request.Body = io.NopCloser(bytes.NewReader(rawBody)) // 塞回供 ShouldBindJSON
    if err := AppendPayRawLog(PayRawLogEntry{
        ReceivedAt: time.Now().Format("2006-01-02 15:04:05"),
        Method: c.Request.Method, Path: c.Request.URL.Path,
        ClientIP: c.ClientIP(), Query: c.Request.URL.RawQuery,
        Headers: c.Request.Header, Body: string(rawBody),
    }); err != nil {
        log.Printf("支付回调原始报文落盘失败: %v", err) // 不阻断主流程
    }

    var body OrderInfo
    if err := c.ShouldBindJSON(&body); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"status": "fail"}) // 非200→平台重试
        return
    }
    if !VerifyPaySignature(config.PayCallback.Token, body.Timestamp, body.Nonce, body.Msg, body.Signature) {
        c.JSON(http.StatusUnauthorized, gin.H{"status": "fail"}) // 验签失败→重试(可修复后补单)
        return
    }
    var pay OrderSuccessPayInfo
    if err := json.Unmarshal([]byte(body.Msg), &pay); err != nil { // msg 二次解析
        c.JSON(http.StatusInternalServerError, gin.H{"status": "fail"})
        return
    }

    cfgAppid := config.PayCallback.Appid
    if cfgAppid == "" {
        log.Printf("未配置 appid,跳过归属校验: order=%s", pay.DedupKey())
    } else if pay.Appid != cfgAppid {
        // P1:不匹配也留痕(不发货),返回 200 停止无意义重试
        SaveUnmatchedOrder(pay, body.Msg)
        c.JSON(http.StatusOK, gin.H{"status": "success"})
        return
    }

    isNew, err := SaveDeliveredOrder(pay, body.Msg) // 幂等落盘
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"status": "fail"}) // 落盘失败→重试
        return
    }
    if isNew {
        // TODO: 真实发货(通知游戏服加游戏币/发道具),此处已保证幂等
        log.Printf("支付订单发货成功: order=%s amount_cent=%d coin=%d",
            pay.DedupKey(), pay.AmountCent, pay.AmountCoin)
    }
    c.JSON(http.StatusOK, gin.H{"status": "success"})
}
```

**返回码策略**:成功/幂等/appid不匹配 → 200;解析/验签/落盘失败 → 非200 触发平台重试。

---

## 7. 订单本地 JSON 存储(pay_order_store.go)

- `PayOrderRecord`:订单业务字段 + `status`(delivered/unmatched_appid) + `raw_msg` + `first/last_notify_at` + `notify_count` + `delivered_at`。
- **幂等**:按 `DedupKey()` 查找,命中则 `notify_count++`、更新 `last_notify_at`,**不重复发货**。
- **原子写**:先写 `.tmp` 再 `os.Rename` 覆盖;`sync.Mutex` 保并发安全。

```go
const (
    StatusDelivered      = "delivered"
    StatusUnmatchedAppid = "unmatched_appid"
)

func SaveDeliveredOrder(info OrderSuccessPayInfo, rawMsg string) (bool, error) {
    return globalPayOrderStore.save(info, rawMsg, StatusDelivered)
}
func SaveUnmatchedOrder(info OrderSuccessPayInfo, rawMsg string) (bool, error) {
    return globalPayOrderStore.save(info, rawMsg, StatusUnmatchedAppid)
}
```

落盘样例:
```json
{ "updated_at": "2026-09-10 10:20:57",
  "orders": [{
    "appid":"<appid>","cp_orderno":"<cp_orderno>","cp_extra":"<extra>",
    "order_no_channel":"<order_no>","amount_cent":648,"amount_coin":6480,"currency":"CNY",
    "status":"delivered","raw_msg":"{...}","first_notify_at":"...","last_notify_at":"...",
    "notify_count":1,"delivered_at":"..." }] }
```

---

## 8. 原始报文日志(pay_raw_log.go,P0)

```go
func AppendPayRawLog(entry PayRawLogEntry) error {
    if entry.ReceivedAt == "" { entry.ReceivedAt = time.Now().Format("2006-01-02 15:04:05") }
    line, _ := json.Marshal(entry); line = append(line, '\n')
    globalPayRawLog.mu.Lock(); defer globalPayRawLog.mu.Unlock()
    f, err := os.OpenFile(globalPayRawLog.path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
    if err != nil { return err }
    defer f.Close()
    _, err = f.Write(line); return err
}
```

JSON Lines(每行一条),`O_APPEND` + 互斥锁,只增不删。仅 POST 入口写(GET ping/验证不写)。

---

## 9. 测试脚本(pay_callback_test.ps1)

PowerShell 脚本,签名逻辑与 `pay_sign.go` 严格一致(**ordinal 排序 + SHA1 + hex 小写**),依次测三个接口:

```powershell
# 关键:.NET 必须用 Ordinal 排序,与 Go sort.Strings 对齐
[System.Array]::Sort($strArr, [System.StringComparer]::Ordinal)
$sha1 = [System.Security.Cryptography.SHA1]::Create()
$hash = $sha1.ComputeHash([System.Text.Encoding]::UTF8.GetBytes((-join $strArr)))
$sig  = ([System.BitConverter]::ToString($hash) -replace '-','').ToLower()
```

运行:`powershell -ExecutionPolicy Bypass -File pay_callback_test.ps1 -Base https://<host> -Token <YOUR_CALLBACK_TOKEN>`

预期:`/v1/ping`→`Status Code 200`;GET 验证→回显 echostr;POST→`{"status":"success"}`。
> 用 `curl.exe -k`(跳过自签证书)对 **IP:端口** 自测只能验证代码逻辑;平台真实回调必须是合规域名(见 SKILL.md 头号铁律)。

---

## 10. 打包与部署

交叉编译 Linux amd64 静态二进制:
```bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o pay-callback-server .
```

部署目录(程序用相对路径,必须从该目录启动):
```
部署目录/
├── pay-callback-server      # 可执行文件,chmod +x
├── config.yaml              # 必需(含 token/appid/路径)
├── cert.pem / key.pem       # HTTPS 证书(若由本服务直接终止 TLS;否则交给 Nginx)
└── data/                    # 运行时自动创建(订单 JSON + 原始日志),需可写
```

对外由 Nginx/Caddy 把备案域名的 **443** 反代到内部端口,回调地址填不带端口的 HTTPS 域名。

---

## 11. 移植到其它语言的检查点

1. 验签:字节序排序 4 个串 → 拼接 → SHA1 → hex 小写 → 大小写不敏感比较。
2. GET 成功回显 `echostr` 纯文本;POST 成功回 HTTP 200。
3. `msg` 是 JSON 字符串,务必二次解析。
4. 幂等键 `order_no_channel`(回退 `cp_orderno`)。
5. P0 入口先无条件落盘原始报文,再做任何校验。
6. 返回码:可恢复失败用非 200 触发平台重试。
7. 发货以服务端 POST 回调为准,绝不信客户端 SDK 回调。

api-reference.md

# 字节虚拟支付回调 · 接口文档

三个 HTTP 接口的完整规格:健康检查、URL 可访问性验证、支付成功通知。
路径与订单字段为字节平台官方约定;示例中的域名 / Token / 密钥均为占位符,请替换为你自己的值。

---

## 通用约定

| 项 | 说明 |
|---|---|
| Base URL | `https://<你的备案域名>`(**443,不带端口**,见 SKILL.md 头号铁律) |
| 回调地址配置 | 开发者平台 → **商业化 → 虚拟支付 → 支付设置**,填「服务器地址」+「服务器回调 Token」 |
| 路径 | `/v1/api/pay/callback` 为示例,可自定义,但**必须与后台配置的完整 URL 一致** |
| 编码 | UTF-8 |
| 成败判定 | 平台**只看 HTTP 状态码**:`200`=成功、不再重试;`非200`=失败、按 `10s/30s/1m/2m/…/2h` 重试,共约 **4h45m** |
| 签名 | GET 与 POST **共用同一套**签名算法(见 §4) |
| 生效前提 | 平台先发 GET 验证可访问性,**验证通过后**才会在支付成功时发 POST |

## 接口一览

| # | 方法 | 路径 | 用途 | 成功响应 |
|---|---|---|---|---|
| 1 | GET | `/v1/ping` | 健康检查(**实现方自定义、非平台强制**) | 纯文本 `Status Code 200` |
| 2 | GET | `/v1/api/pay/callback` | URL 可访问性验证 | 纯文本,原样回显 `echostr` |
| 3 | POST | `/v1/api/pay/callback` | 支付成功通知 | JSON `{"status":"success"}` |

---

## 1. 健康检查 · `GET /v1/ping`

> 可选端点,供负载均衡 / 监控探活,字节平台不强制要求。

- **请求参数**:无
- **响应**:`Content-Type: text/plain`,body 为 `Status Code 200`,HTTP 200

```bash
curl "https://pay.example.com/v1/ping"
# -> Status Code 200
```

---

## 2. URL 可访问性验证 · `GET /v1/api/pay/callback`

平台在后台保存回调地址时发起,用于确认「该地址确实由你控制」。

### 请求参数(query)

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `timestamp` | string | 是 | 时间戳(秒或毫秒字符串均可) |
| `nonce` | string | 是 | 随机串 |
| `msg` | string | 否 | 验证阶段通常为空串 |
| `signature` | string | 是 | 平台计算的签名(SHA1 hex 小写,见 §4) |
| `echostr` | string | 是 | 平台期望被原样回显的随机串 |

### 响应

| 情况 | HTTP | body |
|---|---|---|
| 验签通过 | 200 | **原样回显 `echostr`**(纯文本,非 JSON) |
| 验签失败 | 200 | 空串(平台比对 echostr 不匹配即判验证失败) |

### 示例

```bash
curl "https://pay.example.com/v1/api/pay/callback?timestamp=1700000000&nonce=abc123&msg=&signature=<computed>&echostr=<echostr>"
# 验签通过 -> 原样返回 <echostr>
```

---

## 3. 支付成功通知 · `POST /v1/api/pay/callback`

玩家**支付成功后**平台推送订单(支付失败不推送)。这是**唯一可信的发货依据**。

### 请求 body(JSON)

| 字段 | 类型 | 说明 |
|---|---|---|
| `timestamp` | string | 时间戳 |
| `nonce` | string | 随机串 |
| `msg` | string | **订单 JSON 字符串**,需二次解析为下表结构 |
| `signature` | string | 对 `[token,timestamp,nonce,msg]` 的签名(见 §4) |

### `msg` 二次解析后的订单结构(`OrderSuccessPayInfo`)

| 字段 | JSON key | 类型 | 说明 |
|---|---|---|---|
| Appid | `appid` | string | 小游戏 appid,用于校验订单归属 |
| CpOrderNo | `cp_orderno` | string | 开发者自定义订单号(**基础库 1.55.0+ 才有**) |
| CpExtra | `cp_extra` | string | 开发者透传参数(**基础库 1.55.0+ 才有**) |
| OrderNoChannel | `order_no_channel` | string | 官方交易单号(**总是存在,幂等/对账主键**) |
| AmountCent | `amount_cent` | int64 | 订单金额,单位**分** |
| AmountCoin | `amount_coin` | int64 | 购买的游戏币数量 |
| Currency | `currency` | string | `CNY` 人民币 / `DIAMOND` 钻石 |

### 响应与返回码策略

| 情况 | HTTP | body | 平台行为 |
|---|---|---|---|
| 处理成功(含幂等重复) | 200 | `{"status":"success"}` | 不再重试 |
| appid 不匹配(非本游戏订单) | 200 | `{"status":"success"}` | 不再重试(应留痕但不发货) |
| body 解析失败 | 400 | `{"status":"fail"}` | 重试 |
| 验签失败 | 401 | `{"status":"fail"}` | 重试(修复 Token 后可补单) |
| msg 二次解析失败 | 500 | `{"status":"fail"}` | 重试 |
| 订单落盘失败 | 500 | `{"status":"fail"}` | 重试 |

> 原则:**可恢复的失败返回非 200 触发重试**,避免合法订单静默丢失;**不可恢复/非本游戏**返回 200 停止无意义重试。

### 示例

```bash
# msg 是订单 JSON 字符串(需转义后放入外层 body 的 msg 字段)
curl -X POST "https://pay.example.com/v1/api/pay/callback" \
  -H "Content-Type: application/json" \
  -d '{
        "timestamp": "1700000000",
        "nonce": "abc123",
        "msg": "{\"appid\":\"<your-appid>\",\"cp_orderno\":\"<cp_order>\",\"cp_extra\":\"uid=10086\",\"order_no_channel\":\"<order_no>\",\"amount_cent\":648,\"amount_coin\":6480,\"currency\":\"CNY\"}",
        "signature": "<computed-with-msg>"
      }'
# 成功 -> {"status":"success"}
```

> ⚠️ 签名计算时,`msg` 用的是**未转义的原始订单 JSON 字符串**(即服务端 `ShouldBindJSON` 解析外层后得到的 `body.Msg`),不是转义后的形态。

---

## 4. 签名算法(GET / POST 通用)

```
1. 取四个字符串:token, timestamp, nonce, msg
   - token:后台配置的「服务器回调 Token」
   - msg:GET 验证阶段通常为空串;POST 阶段为订单 JSON 字符串
2. 放入数组,按【字节字典序】升序排序(ordinal / bytewise,非本地化排序)
3. 无分隔符拼接成单个字符串 s
4. signature = lowercase( hex( SHA1(s) ) )
5. 与请求携带的 signature 比较(建议大小写不敏感)
```

**要点**
- 排序必须是**字节序**:Go `sort.Strings`、Java `String.compareTo`、C `strcmp`、JS 默认 `Array.sort()`(纯 ASCII)均可;.NET 必须用 `StringComparer.Ordinal`。
- `msg` 为空串时,加不加入数组结果一致(空串排最前、拼接贡献为空)。
- 输出是 **SHA1 的十六进制小写**,不是 base64。

伪代码:
```text
arr = [token, timestamp, nonce, msg]
sort_ascending_bytewise(arr)
sig = sha1_hex_lower(join(arr, ""))
return sig == request.signature      // 大小写不敏感
```

---

## 5. 幂等与发货

- 平台会重试,同一订单可能**多次到达**,必须按 `order_no_channel`(回退 `cp_orderno`)**去重**,只发货一次。
- 发货以**服务端 POST 回调**为准;客户端 SDK 的支付回调**不可**作为发货依据(仅用于 UI 表现)。
- 建议记录:订单字段 + 原始 `msg` + 首次/最近通知时间 + 通知次数 + 发货状态。

---

## 6. 字段类型速查

| 字段 | 类型 | 备注 |
|---|---|---|
| `timestamp` | string | 秒/毫秒字符串均可能出现 |
| `nonce` / `echostr` / `signature` | string | signature 为 40 位 hex 小写 |
| `msg` | string | POST 时是订单 JSON 字符串,需二次解析 |
| `amount_cent` / `amount_coin` | int64 | 金额单位为**分** |
| `appid` / `cp_orderno` / `cp_extra` / `order_no_channel` / `currency` | string | `cp_*` 仅基础库 1.55.0+ |

---

## 7. 端到端时序

```
开发者                     字节平台                    玩家
  │  后台填回调URL+Token      │                          │
  │◀────GET /callback(echostr)│  ① 可访问性验证           │
  │───200 回显echostr────────▶│  (验签通过才生效)         │
  │                           │                          │
  │                           │◀───────支付成功───────────│  ② 玩家付费
  │◀───POST /callback(order)──│                          │
  │  P0落原始报文→验签→解析msg │                          │
  │  →校验appid→幂等→发货      │                          │
  │──────200 {"status":success}▶│  ③ 收到200即停止重试    │
  │  (非200则按10s/30s/…重试)  │                          │
```

---

## 相关文档

- 通用实现指南与「必须用备案域名」铁律:[SKILL.md](SKILL.md)
- 各接口的 Go 代码实现:[reference-go-implementation.md](reference-go-implementation.md)
最后一次编辑于 2026 年 09 月 20 日
共 0 条评论

相关文章

专题推荐

热门文章

热门问答