代码 PIX 收款回调只算通知:CRC16 得算到 6304、txid 只有 25 个字符、退款复用 endToEndId

2026-11-19 09:02:22

PIX 收款回调只算通知:CRC16 得算到 6304、txid 只有 25 个字符、退款复用 endToEndId

国内接微信、支付宝的习惯是「下单 → 等回调 → 回调里验签 → 标记已付」。PIX 不是这个形状,回调只承担「通知」这一层,最终状态一律以主动回查为准:GET /cob/{txid} 返回 CONCLUIDA 才算真正到账(Bacen openapi.yaml 的 Cobranca 状态定义)。把回调当收款事实,是后面大多数漏单与重复入账的来源。

一、PIX 的接入是四个动作,不是一个回调

PIX 是分层契约,动作分开:

  1. 建收费单:PUT /cob/{txid},自己定 txid,返回 201,响应里带 location 与 pixCopiaECola(那段 BR Code 字符串)。也可以用 POST /cob,但这时 txid 由 PSP 生成,就失去了「订单号即 txid」的对账便利(Bacen openapi.yaml:POST /cob 的 txid 由 PSP 生成)。
  2. 渲染二维码:拿 pixCopiaECola 给用户扫。
  3. 接收通知:PSP 通过 webhook POST 到 {webhookUrl}/pix,通知「有 Pix 进来了」。
  4. 反查确认:GET /cob/{txid},status 为 CONCLUIDA 才算真收到;GET /pix/{e2eid} 可以按端到端号查这笔清算。

退款是第五个动作:PUT /pix/{e2eid}/devolucao/{id},路径参数是 e2eid,不是 txid(Bacen openapi.yaml 的 devolucao 路径)。

契约来源是 Bacen 的 OpenAPI:bacen/pix-api 的 openapi.yaml,当前 2.x。Efí/Gerencianet、Mercado Pago、BB、Itaú 等 PSP 实现同一份契约,但把 webhook 的 SLA、重试次数、超时留给自己定义(各家 PSP 文档,需逐个核对)。这也是「文档照抄能跑通,上线后漏单」成为常见事故的原因。

二、webhook 四个固定事实

按 Bacen 规范与 Efí 文档:

  • 路径是追加的,不是整段替换。注册 https://erp.example.com/api/pix,PSP 实际 POST 到 https://erp.example.com/api/pix/pix(Efí 文档的 {webhookUrl}/pix 规则)。路由写成精确匹配 /api/pix 的话,每次投递都 404,PSP 那边只看到「没应答」。Efí 允许在注册 URL 尾部加 ?ignorar=,让 PSP 不再追加后缀。
  • 只有带 txid 的 Pix 才会通知。静态码(贴在店里的固定二维码)如果没有 62-05 字段,收钱不会触发任何 webhook(Manual de Padrões 对 62-05 的定义;Efí 文档对静态码回调的说明)。「静态码 + 只依赖回调」等于永久漏单,这部分钱只能靠 GET /pix?inicio=&fim= 定时扫出来。
  • 一个 chave 只能绑一个 webhook URL,一个 URL 可以服务多个 chave(Bacen /webhook/{chave} 的约束)。换环境(沙箱换生产)忘了重新 PUT,就会出现「生产收钱、沙箱地址收到 404」的排障现场。
  • 没有 HMAC 签名头。Bacen 规范里 webhook 由 PSP 以 mutual TLS 调用,认证发生在证书层,不在 body 上。从 Stripe、微信 v3 迁过来的人第一反应是找 X-Signature,找不到就会走两个极端:不校验直接信任 body(伪造回调就能白拿货),或者自己编一套签名规则。正确做法是两件事:TLS 层校验客户端证书(或有条件时做 IP 白名单),业务层永远不信 body 的 valor,一律 GET /cob/{txid}?revisao= 回查。

三、txid 有三套长度,一套都不许混

同一个业务概念在三个位置有不同规则(Bacen openapi.yaml 的 TxId pattern、Manual de Padrões 的 62-05 字段约束):

位置允许长度字符集说明
API PUT /cob/{txid}26–35[a-zA-Z0-9]建单时你传的 txid
GET /pix、webhook body 里的 txid1–35[a-zA-Z0-9]静态码可能带很短的 txid,所以读的时候别按 26 位校验
BR Code 62-05(静态码)≤ 25[a-zA-Z0-9]写进二维码的那段
BR Code 62-05(动态码)固定 ***—txid 从 payload JSON 里取,QR 里写 ***

最容易在第一步就卡住的地方:拿 UUID 当 txid 是最自然的想法。带横线的 c3e0e7a4-e7f1-469a-9f78-2d3d4999343c 长度 36、含 -,直接违反 API 的字符集和长度;去掉横线的 32 位 hex 能过 API 的 26–35,但同一串塞进静态 BR Code 的 62-05,就超过 25 上限(BR Code 手册的 62-05 长度上限)。所以建单 txid 建议规则化:订单ID + 补齐 到 30 位左右,纯字母数字,静态码场景单独截到 25。

另外 txid 在「同一 recebedor 的 CPF/CNPJ + 同一 PSP」下永久唯一,收费单被删除后也不能复用(Bacen 规范)。这条对重试设计有直接影响:网络超时重发 PUT /cob/{txid} 用同一个 txid 是安全的(服务端已存在同单),但「删掉重建、换个新号再建」会让对账表里同一个订单挂两张单。具体重复 PUT 返回 200 还是 201,各家 PSP 不完全一致,接入时要抓一次真实响应确认,不要照抄——需自行验证。

四、BR Code:TLV、CRC16 和那两个字节

BR Code 是 EMV QRCPS-MPM 的巴西变体,编码是 TLV:两位 ID + 两位长度 + 值,无分隔符拼接。26 和 62 是模板,值本身又是一串 TLV,解析器必须递归(BR Code 手册 v2.0.0 的 TLV 定义)。

静态码必填字段(官方示例顺序):

00 02 01                                  00 Payload Format Indicator 固定 01
26 xx 0014br.gov.bcb.pix 01xx      26 Merchant Account Information
52 04 0000                                52 MCC,未提供填 0000
53 03 986                                 53 币种,986 = BRL
54 0x 25.90                               54 金额,可选,十进制字符串
58 02 BR                                  58 国家
59 13 Fulano de Tal                       59 商户名,≤ 25
60 08 BRASILIA                            60 城市,≤ 15
62 07 05 03 ***                           62 附加数据,05 子域放 txid
63 04 1D3D                                63 CRC16

三条具体约束:

金额是十进制字符串,不是分。 54 写 25.90,带小数点、不带千分位、不带货币符号。最小粒度两位小数(0、1.00、123.99 是规范里的合法例子),写 25.9 属于格式不合规(BR Code 手册 54 字段)。这跟 Stripe 用最小货币单位、PayPal 用两位小数是完全不同的口径,三家混在一个系统里就必须在边界处显式转换。

CRC16 要算到 6304 为止。 参数是 CRC-16/CCITT-FALSE:多项式 0x1021、初值 0xFFFF、不反射、不做最终 XOR。计算输入是「从第一个字节到 6304 这四字节,包含 6304」,结果四位大写 hex 跟在后面(BR Code 手册的 CRC-16-CCITT-FFFF 定义)。少算这四字节,二维码照样能被任何扫码器解出文本,只有银行 App 拒收——这类错误在本地测不出来,要拿真机扫。自检向量:CRC16("123456789") == 0x29B1;官方静态码示例的 CRC 是 1D3D,可以当回归用例。

Go 实现:

func tlv(id, val string) string {
return id + fmt.Sprintf("%02d", len(val)) + val
}

func crc16(b []byte) string {
var crc uint16 = 0xFFFF
for _, c := range b {
crc ^= uint16(c) getContent(), true);

foreach ($payload['pix'] ?? [] as $pix) {
// 复合去重键,见上一节
$key = $pix['endToEndId'] . ':' . ($pix['devolucoes'][0]['id'] ?? 'recv');
if (!Idem::claim($key)) {
continue;
}
PixEvent::dispatch($pix['txid'] ?? null, $pix['endToEndId'], $key); // 入队
}

return response('', 200); // 只回状态码,越快越好
}

// worker
public function handle(string $txid, string $e2eid)
{
if ($txid === null) {
// 静态码,没有 txid,只能按 e2eid 在 GET /pix 结果里找
$pix = $this->psp->getPix($e2eid);
} else {
$cob = $this->psp->getCob($txid);
if ($cob['status'] !== 'CONCLUIDA') {
return; // 还没清算完,交给补单任务
}
}
$this->orders->markPaid($txid, $e2eid, $this->toCents($cob['valor']['original']));
}

solicitacao 回调的 valor 是字符串("110.00"),不要 intval() 了事——直接转 int 会得到 110,和库里的 11000 分比差 100 倍。换到 PIX 上还是同一个坑。

七、漏单的兜底:按时间窗扫

再完整的 webhook 也会漏:路径写错 404、部署时短暂 502、超出 PSP 的重试上限。兜底任务用 GET /pix?inicio=&fim= 按时间窗拉取已清算流水,和本地订单做差集:

  • 查到本地没有的 endToEndId → 补单,走和 webhook 同一个状态机函数
  • 有 txid 但订单不存在 → 客户多付/重复付,进人工复核队列
  • 金额和 txid 对不上 → 两条单独记账,不要强行合并

窗口建议比 PSP 最长重试间隔的一半还短,常规 15 分钟一轮,零点做一次全量日对账。注意 GET /pix 的分页(paginaAtual / itensPorPagina)和时间过滤都是必填(Bacen openapi.yaml 的 /pix 参数),别用「不限时间」的查询打满 PSP 的 QPS。

八、排障顺序

按这个顺序查,比看日志猜快:

  1. PSP 到底投了没:PSP 后台的 webhook 投递记录(Efí 有),或者你自己 nginx access log 里有没有 POST /api/pix/pix。
  2. 路径对不对:看的是 /api/pix 还是 /api/pix/pix。404 基本都在这里(Efí 文档的追加规则)。
  3. 有没有 txid:这笔是静态码还是动态码。静态码收不到回调是设计如此,不是故障。
  4. 去重键是不是把退款吞了:查幂等表里有没有 endToEndId 只有一行、后面没有任何退款行的记录。
  5. 状态是不是 CONCLUIDA:GET /cob/{txid} 返回 ATIVA 说明只是生成了收费单,没人付。
  6. 金额单位:110.00 与 11000 的差异几乎必然导致「已付款但订单金额不符」的报警。

九、本文依据与未实测

依据:Bacen 的 API 契约 bacen/pix-api(openapi.yaml,v2.x,含 /cob/{txid}、/pix、/webhook/{chave}、/pix/{e2eid}/devolucao/{id} 与 TxId/EndToEndId 的 pattern);Manual de Padrões para Iniciação do Pix(静态/动态 QR 字段表、62-05 上限 25、CRC 多项式与初值);Manual do BR Code(TLV 结构、字符集、CRC-16-CCITT-FFFF);Efí 的 webhook 文档({webhookUrl}/pix 追加规则、?ignorar=、60 秒超时、2xx、回调 JSON 样例);pix-visualized 对 txid 六种上下文与去重键的整理。

未实测(需自行验证):各家 PSP 的 mTLS 证书签发流程与客户端证书校验实现(BB、Itaú 与 Efí 各不相同,需要按签约方文档做);重复 PUT /cob/{txid} 的具体状态码;PSP 侧重试次数与退避。这些必须在接入时用真实凭据打一遍,不要按本文推断上线。

项目信息

复制全文 生成海报 PIX 巴西支付 webhook BR Code 支付对账 mTLS

推荐文章

程序员茄子在线接单