Z Zise Developers

card.application.awaiting_bind

实体卡已可绑定

何时发

实体卡到了用户手里、申请单进入 awaiting_bind 之后。下游库存模式的标准申请 在审核通过进入履约队列后会自动当面交付到这一档;平台自营则是线下面交确认, 或邮寄运单标成用户已签收。data.id 是公开开卡申请单号(已带 cap_), 回查走 GET /v1/cards/applications/{data.id},然后 POST /v1/cards/bind → POST /v1/cards/{id}/activate。 这不是开卡成功:卡还没激活,不要当成已可用。 仅 shipped(货还在路上)不发;绑卡之后的 pending_activation 也不发。 激活成功仍走 card.application.approved 与 card.status.updated。 ⚠ 平台自营会员不发。

事件体

{
  "event_id": "evt_b7c1e02a9d3f4e18ac552d61ab0f9e77",
  "event_type": "card.application.awaiting_bind",
  "created_at": "2026-09-21T06:37:35Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "card_application",
    "id": "cap_9c41f0a8-27d5-4e63-b0a9-1f7c85d2e340",
    "external_member_id": "u_88123",
    "status": "awaiting_bind",
    "status_version": 5
  }
}

事件体字段

字段类型说明
idstring去重用这个。evt_…,同一事件重投时不变。
typestring固定为 card.application.awaiting_bind
created_atstring事件产生时刻(RFC3339)。不是投递时刻 —— 重投时它不变。
data.objectstring对象类型,决定 data.id 该拿去查哪个端点
data.idstring对象 ID,拿它回查详情
data.statusstring认不出的值按未知处理并告警,不要 fallback 成「处理中」
data.status_versionnumber单调递增,用它把慢到的旧状态丢掉

验签与去重

验签用原始请求体字节,不要先解析再重新序列化 —— 你的 JSON 库与我方的键顺序、空格几乎一定不同,重新序列化出来的签名一定对不上, 而那个错误长得像「密钥配错了」。

// Node · 放在解析 JSON 之前
const raw = await readRawBody(req);            // Buffer / string,别用已解析的 req.body
const expect = crypto.createHmac("sha256", WEBHOOK_SECRET).update(raw).digest("hex");
const got = req.headers["z-signature"];        // 形如 t=<unix>,v1=<hex>
if (!timingSafeEqual(expect, parseV1(got))) return res.status(400).end();

// 去重:用信封的 id,不是 data.id
if (await seen(JSON.parse(raw).id)) return res.status(200).end();

完整做法(含时间戳容差与重投语义)见 Webhook 指南。