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 'authorization: Bearer $TOKEN' \
  -H 'x-zise-merchant: $MERCHANT_ID' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'x-idempotency-key: $(uuidgen)' \
  -H 'content-type: application/json' \
  -d '{
    "amount": "10.50"
  }'
const res = await fetch(
  "https://api.zise.com/v1/cards/{id}/withdrawals",
  {
    method: "POST",
    headers: {
      "authorization": "Bearer $TOKEN",
      "x-zise-merchant": "MERCHANT_ID",
      "x-on-behalf-of": "MEMBER_ID",
      "x-idempotency-key": "crypto.randomUUID()",
      "content-type": "application/json"
    },
    body: JSON.stringify({
      "amount": "10.50"
    }),
  },
);
// 金额一律按字符串读，不要 JSON.parse 成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/cards/{id}/withdrawals",
    headers={
        "authorization": "Bearer $TOKEN",
        "x-zise-merchant": "$MERCHANT_ID",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$(uuidgen)",
        "content-type": "application/json"
    },
    json={
        "amount": "10.50"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()