Z Zise Developers
/
API 参考 › 发卡

改账单地址（美国线上商户 AVS 校验的对象）

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

账单地址与卡号一起提交给收单机构做 AVS 比对，对不上就拒付。

用户搬家之后不改这里，那张卡在 AVS 严格的商户上会从此刷不过。

⚠ 先读 GET /v1/cards/{id} 的 billing_address_updatable。

不是每个 BIN 都允许改（这是卡组织/发卡行那一层的限制，不是我方的

开关）。为 false 的卡不该渲染这个入口 —— 调用会拿到

product_not_available，而那对终端用户不可解释。

⚠ 200 表示上游已确认（这一条是同步的，与 /limits 相反 ——

那一条的 200 只表示「我方已记下」）。收到 502 时结果不明：

我方不会把新地址写进库（写了会让我方下发给你的地址与卡组织实际

比对的那一份分叉，而 AVS 拒付时唯一能查的就是这两份对不对得上）。

用同一把幂等键重试，再读一次卡详情确认。

⚠ state 不是必填 —— 大量国家没有州/省这一级。

country 只校验形状（ISO-2 两位大写），我方不拿一张自己的国家清单

去挡：挡错的代价是用户填了真地址却被拒。

前置条件

  • 卡不在 closed / expired / replaced
  • 该卡的 BIN 允许改账单地址（卡详情的 billing_address_updatable）

路径参数

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

请求体

字段类型必填说明
address string 必填 街道地址
city string 必填
state string 可选 州/省。没有这一级的国家留空。
country string 必填 ISO 3166-1 alpha-2，大写
postal_code string 必填

响应

200上游已确认
{
  "id": "crd_9f2c1b7a-3d51-4a2e-9c08-6b1f0d4e77aa",
  "billing_address": {
    "address": "1600 Amphitheatre Pkwy",
    "city": "Mountain View",
    "state": "CA",
    "country": "US",
    "postal_code": "94043"
  }
}
400invalid_fields 必填项缺失 / country 不是 ISO-2（带 fields 数组）· state_invalid 卡已注销/过期 · product_not_available 这张卡的 BIN 不允许改账单地址，或凭据不全 · invalid_request 上游拒绝了这份地址
404not_found 卡不存在或不在这个会员名下
502upstream_error 结果不明，我方未落库。用同一把幂等键重试。
请求 
curl -X PATCH 'https://api.zise.com/v1/cards/{id}/billing-address' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'content-type: application/json' \
  -d '{
    "address": "1600 Amphitheatre Pkwy",
    "city": "Mountain View",
    "state": "CA",
    "country": "US",
    "postal_code": "94043"
  }'
const res = await fetch("https://api.zise.com/v1/cards/{id}/billing-address", {
  method: "PATCH",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "address": "1600 Amphitheatre Pkwy",
    "city": "Mountain View",
    "state": "CA",
    "country": "US",
    "postal_code": "94043"
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();
import requests

res = requests.patch(
    "https://api.zise.com/v1/cards/{id}/billing-address",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "content-type": "application/json",
    },
    json={
      "address": "1600 Amphitheatre Pkwy",
      "city": "Mountain View",
      "state": "CA",
      "country": "US",
      "postal_code": "94043"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()
req, _ := http.NewRequest("PATCH", "https://api.zise.com/v1/cards/{id}/billing-address",
    strings.NewReader(`{
  "address": "1600 Amphitheatre Pkwy",
  "city": "Mountain View",
  "state": "CA",
  "country": "US",
  "postal_code": "94043"
}`))
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}/billing-address"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("content-type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("""
{
  "address": "1600 Amphitheatre Pkwy",
  "city": "Mountain View",
  "state": "CA",
  "country": "US",
  "postal_code": "94043"
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double
$ch = curl_init('https://api.zise.com/v1/cards/{id}/billing-address');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "address": "1600 Amphitheatre Pkwy",
  "city": "Mountain View",
  "state": "CA",
  "country": "US",
  "postal_code": "94043"
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval
200 
{
  "id": "crd_9f2c1b7a-3d51-4a2e-9c08-6b1f0d4e77aa",
  "billing_address": {
    "address": "1600 Amphitheatre Pkwy",
    "city": "Mountain View",
    "state": "CA",
    "country": "US",
    "postal_code": "94043"
  }
}