Z Zise Developers
/
卡发行 › API 参考 › 卡内资金

卡内资金转出到钱包（≠ 链上提现）

POST /v1/cards/{id}/withdrawals scope: cards:write
代会员调用 · 必带 x-on-behalf-of 需 x-idempotency-key 动钱 · 卡内资金（`member.card` 桶）→ 会员可用余额；手续费按产品配置
这个端点会动钱

失败处置见下方响应表。超时（504）用同一把幂等键重试——我方可能已经处理完；业务失败要换新键，同键会原样返回那次失败。

把卡里的钱退回会员的可用余额。这不是链上提现 —— 钱一步都没离开我方，

链上提现是另一条线（withdrawals）。

⚠ 只退卡本币（USD），不原路退回。 用 USDT 充的卡，转出拿到的是 USD。

想拿回 USDT 得再走一次正式兑换。这一条要写进你的界面 ——

按「原路退回」的假设做提示，用户会以为我方吞了他的币。

⚠ 金额会先向下取整到上游能表示的粒度（USD 两位小数）再建单：

传 "10.505" 实际转出 10.50。方向取向下是刻意的 ——

多退的那零头卡里根本没有。

与充值一样是两段异步：201 只表示「已受理」，到账由回调收敛；

同一把幂等键重放回放的是原始结论（失败仍回失败）。

前置条件

  • 卡在这个会员名下
  • 会员不在资金保护态
  • 金额 ≤ 可转出上限（= 上游余额 − 已授权未结算，且不超过我方账本记的卡内资金）

路径参数

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

请求体

字段类型必填说明
amount string 必填 转出金额，卡本币口径的十进制串。USD 实际按两位小数向下取整："10.50"

响应

201已受理。status：processing（等上游确认）· completed（共享额度卡当场完成）。
{
  "id": "cwd_5b1c7e08-2f94-4a6d-9c33-71ae0d4b8265",
  "status": "processing"
}
400product_not_available 供应商或产品不可用 · state_invalid 卡状态不允许 · idempotency_key_required / idempotency_key_invalid ⚠ 超出可转出金额、上游拒绝、资金保护态，目前以 500 api_error 返回 （内部有码，未登记进对外目录）。
404not_found 卡不存在或不在这个会员名下
504upstream_timeout 结果不明 —— 同一把幂等键重试
请求 
curl -X POST 'https://api.zise.com/v1/cards/{id}/withdrawals' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "amount": "10.50"
  }'
const res = await fetch("https://api.zise.com/v1/cards/{id}/withdrawals", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "amount": "10.50"
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/cards/{id}/withdrawals",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={
      "amount": "10.50"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()
req, _ := http.NewRequest("POST", "https://api.zise.com/v1/cards/{id}/withdrawals",
    strings.NewReader(`{
  "amount": "10.50"
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
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}/withdrawals"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "amount": "10.50"
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double
$ch = curl_init('https://api.zise.com/v1/cards/{id}/withdrawals');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "amount": "10.50"
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval
201 
{
  "id": "cwd_5b1c7e08-2f94-4a6d-9c33-71ae0d4b8265",
  "status": "processing"
}