Z Zise Developers
/
API 参考 › 发卡

充值到卡试算（不外呼上游）

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

纯浏览动作，不锁钱、不建单、不问上游 —— 「看看要花多少钱」不该在

上游堆出一笔待处理的询价。

⚠ amount 是基准额（我方按它加溢价与手续费算出你要付的

customer_total），不是用户实付。customer_total > amount 是常态。

⚠ 跨币种到卡额这里只是估算（我方按 1:1 估），真实汇率由上游在

POST /v1/cards/{id}/topups 那一刻给。界面上要标注「以实际成交为准」。

⚠ 响应里的四个金额都是最小单位整数串：customer_total / fee 按

ledger_scale（源资产），arrival_amount 按 card_scale（卡本币）。

两个精度不同，别用同一个除数。

溢价我方不下发 —— 下发等于把「上游成本 = 展示价 ÷ (1+markup)」这道题

送给任何抓包的人。

前置条件

  • 卡在这个会员名下，且该产品已启用
  • 金额在产品的 topup_min 与单笔上限之间

路径参数

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

请求体

字段类型必填说明
amount string 必填 基准额，源资产口径的十进制串。USDT 为 6 位以内："100.00"
source_asset string 可选 扣款资产。省略则按该会员的支付优先级自动挑一个。 ⚠ 它是「偏好」不是「指令」：传了一个已下架/不在产品清单里的 资产时我方静默回落到优先级，不报错 —— 响应里的 source_asset 才是真正会被扣的那个，请读它而不是回显你传的值。

响应

200试算结果（此报价不落库、不占用任何额度）
{
  "customer_total": "100500000",
  "arrival_amount": "100000000",
  "fee": "500000",
  "source_asset": "USDT",
  "ledger_scale": 6,
  "card_currency": "USD",
  "card_scale": 6,
  "note": "跨币种到卡额以上游实际成交为准"
}
400product_not_available 产品未启用，或没有一个可用的扣款资产 · state_invalid 卡状态不允许 ⚠ 低于最低额 / 超单笔上限 / 金额串格式非法，目前都以 500 api_error 返回 —— 内部有明确的码但还没登记进对外码目录。 这是最常撞到的一档，先按「500 也可能是你的入参问题」处理，别无限重试。
404not_found 卡不存在或不在这个会员名下
请求 
curl -X POST 'https://api.zise.com/v1/cards/{id}/topup-quotes' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'content-type: application/json' \
  -d '{
    "amount": "100.00",
    "source_asset": "USDT"
  }'
const res = await fetch("https://api.zise.com/v1/cards/{id}/topup-quotes", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "amount": "100.00",
    "source_asset": "USDT"
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/cards/{id}/topup-quotes",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "content-type": "application/json",
    },
    json={
      "amount": "100.00",
      "source_asset": "USDT"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()
req, _ := http.NewRequest("POST", "https://api.zise.com/v1/cards/{id}/topup-quotes",
    strings.NewReader(`{
  "amount": "100.00",
  "source_asset": "USDT"
}`))
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}/topup-quotes"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "amount": "100.00",
  "source_asset": "USDT"
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double
$ch = curl_init('https://api.zise.com/v1/cards/{id}/topup-quotes');
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'
{
  "amount": "100.00",
  "source_asset": "USDT"
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval
200 
{
  "customer_total": "100500000",
  "arrival_amount": "100000000",
  "fee": "500000",
  "source_asset": "USDT",
  "ledger_scale": 6,
  "card_currency": "USD",
  "card_scale": 6,
  "note": "跨币种到卡额以上游实际成交为准"
}