Z Zise Developers
/
卡发行 › API 参考 › 生命周期

挂失 / 报盗卡（不可逆，仅实体卡）

POST /v1/cards/{id}/lost scope: cards:write
代会员调用 · 必带 x-on-behalf-of

⚠ 与 /freeze 是两件事，不是一件事的两种说法。

冻结可逆（/unfreeze 就在隔壁），挂失不可逆：卡进 lost 之后

只能走补卡（POST /v1/cards/{id}/replacements，重新收邮费与制卡成本，

且余额不在新旧卡之间直接转）。责任划分也不同 —— 报了挂失之后的

盗刷由发卡方承担，而冻结不构成这个声明。

所以「用户说卡不见了」的正确处置往往是先 /freeze（可撤销、

当场推给上游、后续授权会被拒），确认真的丢了再来这一条。

⚠ 虚拟卡不支持（上游限制），会拿到 state_invalid。

⚠ 这一档状态迁移不触发 webhook。 我方的 card.status.updated

只由状态同步器发出，而挂失是一次直接写入。请在 200 之后自己把

本地状态置为 lost，或回读 GET /v1/cards/{id}。

前置条件

  • 实体卡
  • 卡不在 closed / closing / lost

路径参数

字段类型必填说明
id string 必填 卡 id
字段类型必填说明
x-idempotency-key string 必填
x-step-up string 可选 终端用户在我方托管屏完成强认证后拿到的 challenge_id
x-on-behalf-of string 必填 代哪个会员调用

请求体

字段类型必填说明
kind "lost" | "stolen" 可选 认不出的值一律按 lost 处理。

响应

200已挂失
{
  "id": "crd_9f2c1b7a-3d51-4a2e-9c08-6b1f0d4e77aa",
  "status": "lost",
  "kind": "stolen"
}
400step_up_required 需要强认证（带 challenge_id / hosted_url / expires_at， 终端用户完成后用同一把幂等键、同一份 body 重发并带 x-step-up）· state_invalid 虚拟卡 / 卡已注销 / 已经挂失过 · product_not_available 供应商不可用
404not_found 卡不存在或不在这个会员名下
请求 
curl -X POST 'https://api.zise.com/v1/cards/{id}/lost' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'content-type: application/json' \
  -d '{
    "kind": "stolen"
  }'
const res = await fetch("https://api.zise.com/v1/cards/{id}/lost", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "kind": "stolen"
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/cards/{id}/lost",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "content-type": "application/json",
    },
    json={
      "kind": "stolen"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()
req, _ := http.NewRequest("POST", "https://api.zise.com/v1/cards/{id}/lost",
    strings.NewReader(`{
  "kind": "stolen"
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// 金额字段用 string 接，不要 float64
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zise.com/v1/cards/{id}/lost"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "kind": "stolen"
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double
$ch = curl_init('https://api.zise.com/v1/cards/{id}/lost');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "kind": "stolen"
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval
200 
{
  "id": "crd_9f2c1b7a-3d51-4a2e-9c08-6b1f0d4e77aa",
  "status": "lost",
  "kind": "stolen"
}