Z Zise Developers
/
API 参考 › 发卡

整份替换商户 / MCC 名单（白名单或黑名单，二选一）

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

差旅卡挡掉赌博 / 成人 / 加密类 MCC，采购卡锁定几家供应商，

订阅卡锁死单一商户 —— 都在这一个端点上。

⚠ PUT 是整份替换，不是追加。 上游一张卡只有一份规则

（白名单与黑名单不能并存），所以每次都要把完整名单发全。

当成追加用的话，你以为在加一条，实际是把整份规则换掉了。

⚠ merchant_names 与 mcc_list 不能同时为空。空规则在白名单

语义下意味着「一家都不许刷」，而你几乎不可能是这个意思 ——

要取消限制请用 DELETE。

⚠ 200 表示上游已确认收下（响应里 synced: true）。

收到 502 upstream_error 时规则可能已经生效了：我方已把你要的

名单存下来（下次改动以它为基线），但没有确认。用同一把幂等键重试。

merchant_names 匹配的是清算报文里的商户名，各收单机构写法不一

（AMAZON / AMZN Mktp US / AMAZON.COM*2K4TY）——

以你在 GET /v1/cards/{id}/transactions 里看到的 merchant_name

为准，别照着品牌官网写。

前置条件

  • 卡不在 closed / expired / replaced
  • 该供应商支持卡级名单（merchantRules 能力位）

路径参数

字段类型必填说明
id string 必填 卡 id
字段类型必填说明
x-idempotency-key string 必填
x-on-behalf-of string 必填 代哪个会员调用

请求体

字段类型必填说明
rule_type "white" | "black" 必填 white = 只准在名单内消费；black = 名单内一律拒。 一张卡只能有一种。
merchant_names string[] 可选 商户名清单，最多 200 条。空数组 = 不按商户名判。
mcc_list string[] 可选 MCC 清单（四位数字，ISO 18245），最多 200 条。

响应

200上游已确认
{
  "id": "crd_9f2c1b7a-3d51-4a2e-9c08-6b1f0d4e77aa",
  "rule_type": "black",
  "merchant_names": [],
  "mcc_list": [
    "7995",
    "5967",
    "6051"
  ],
  "synced": true,
  "synced_at": "2026-08-13T02:11:47.000Z"
}
400invalid_fields MCC 不是四位数字 / 两份清单都空 / 条数超 200 （带 fields 数组，逐条告诉你哪一项坏了）· state_invalid 卡已注销/过期 · product_not_available 这家供应商不支持卡级名单，或凭据不全 · invalid_request 上游拒绝了这份名单
404not_found 卡不存在或不在这个会员名下
502upstream_error 结果不明 —— 规则可能已经建上了。 用同一把幂等键重试；换新键不会让上游多出第二份规则 （它一张卡只有一份），但会让你的对账多一条无主的键。
请求 
curl -X PUT 'https://api.zise.com/v1/cards/{id}/merchant-rules' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'content-type: application/json' \
  -d '{
    "rule_type": "black",
    "merchant_names": [],
    "mcc_list": [
      "7995",
      "5967",
      "6051"
    ]
  }'
const res = await fetch("https://api.zise.com/v1/cards/{id}/merchant-rules", {
  method: "PUT",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "rule_type": "black",
    "merchant_names": [],
    "mcc_list": [
      "7995",
      "5967",
      "6051"
    ]
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();
import requests

res = requests.put(
    "https://api.zise.com/v1/cards/{id}/merchant-rules",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "content-type": "application/json",
    },
    json={
      "rule_type": "black",
      "merchant_names": [],
      "mcc_list": [
        "7995",
        "5967",
        "6051"
      ]
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()
req, _ := http.NewRequest("PUT", "https://api.zise.com/v1/cards/{id}/merchant-rules",
    strings.NewReader(`{
  "rule_type": "black",
  "merchant_names": [],
  "mcc_list": [
    "7995",
    "5967",
    "6051"
  ]
}`))
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}/merchant-rules"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("content-type", "application/json")
    .method("PUT", HttpRequest.BodyPublishers.ofString("""
{
  "rule_type": "black",
  "merchant_names": [],
  "mcc_list": [
    "7995",
    "5967",
    "6051"
  ]
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double
$ch = curl_init('https://api.zise.com/v1/cards/{id}/merchant-rules');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "rule_type": "black",
  "merchant_names": [],
  "mcc_list": [
    "7995",
    "5967",
    "6051"
  ]
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval
200 
{
  "id": "crd_9f2c1b7a-3d51-4a2e-9c08-6b1f0d4e77aa",
  "rule_type": "black",
  "merchant_names": [],
  "mcc_list": [
    "7995",
    "5967",
    "6051"
  ],
  "synced": true,
  "synced_at": "2026-08-13T02:11:47.000Z"
}