POST /v1/transfers

发起站内转账（一步到账，没有待审态）

Scope transfers:write 代会员调用 · 必带 x-on-behalf-of 需 x-idempotency-key 动钱 · 扣付款会员的可用余额 + 增收款会员的可用余额（一步到账）

这个端点会动钱

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

成交那一刻钱已经是对方的可用余额 —— 没有撤销、没有追回。

要挡大额请让平台配 max_amount；large_amount_threshold 只打标不拦截。

sender_debit（你的会员实扣）与 receiver_credit（对方实收）

不一定相等：手续费由谁付是平台的配置项。

⚠ 跨商户转账一律「查无此人」，与「这个人不存在」同一个响应。

这不是一道可以放宽的配置：站内转账是会员到会员的两条腿，没有平台腿，

所以账本那一侧的归属保护对它不执行 —— 这道闸是唯一的兑现处。

⚠ memo 会被截断到 140 字符，不报错。你的界面该按更短的长度限，

否则用户写的话会被悄悄剪掉后半段。

⚠ 幂等键同时受两层保护：我方的开放 API 幂等层（同键回放上次响应），

以及库里带商户前缀的唯一索引。所以同一把键既拿不到第二笔钱，

也拿不到别的商户那一单。

⚠ 经这个端点发起的转账不发 transfer.completed webhook。

那条事件目前只在「会员自己在 App 里转」的那一侧发出。你这一侧

转账成功与否就在这次响应里；**收款方那边要靠

GET /v1/transfers（收发两侧都在内）去查**，别等事件。

前置条件

该资产的站内转账已启用，且总闸未关
收款人与发起方同商户，且未被封禁 / 冻结 / 实名不足
发起方该资产可用余额 ≥ sender_debit（含手续费那一档）

字段	类型	必填	说明
`x-on-behalf-of`	string	必填	付款方。收款人只在这个会员的商户内解析。
`x-idempotency-key`	string	必填	UUID。同键重放拿回原单（`duplicated: true`），不会转第二次。

请求体

字段	类型	必填	说明
`asset`	string	必填	资产代码，如 `USDT`。大小写不敏感。
`recipient_type`	"uid" \| "email" \| "phone"	可选	标识方式，缺省 `uid`。必须在服务端下发的白名单里。
`recipient`	string	必填	标识值。选 `phone` 时必须是 E.164。
`amount`	string	必填	转账面额（不是实扣、也不是实收）。字符串定点，位数 = 该资产 `ledger_scale`。手续费由谁付决定了它与 `sender_debit` / `receiver_credit` 的关系。USDT 是 6 位，形如 120.000000
`memo`	string	可选	附言。超过 140 字符会被静默截断。

响应

200幂等命中：这一次没有真的转账，拿回的是原来那一单。 ⚠ 这一支的响应体只有三个字段（比 201 少了金额那几个），别按 201 的形状去解析。

{
  "id": "itr_5c8a91d2-77b3-4a6e-b0f1-2d4a9e7c1330",
  "status": "completed",
  "duplicated": true
}

201已到账。status 恒为 completed（没有待审态、没有中间态）。金额是定点十进制串。

{
  "id": "itr_5c8a91d2-77b3-4a6e-b0f1-2d4a9e7c1330",
  "status": "completed",
  "asset": "USDT",
  "amount": "120.000000",
  "sender_debit": "120.500000",
  "receiver_credit": "120.000000"
}

400已登记的对外码：invalid_request 金额格式 / 请求体不合法 · product_not_available 站内转账总闸关着 · request_rejected 发起方被冻结 / 销户 / 命中风控 · idempotency_key_required · idempotency_key_invalid · member_context_required · member_not_found ⚠ 还落在 500 api_error：该资产未启用 · 查无此人（含跨商户）· 转给自己 · 收款方被封禁 / 冻结 / 实名不足 · 发起方实名不足 · 低于起转 / 高于单笔上限 · 超发起方日限额 · 超收款方日收额度 · 余额不足。

409idempotency_key_reused · idempotency_in_progress

调用样例

curl -X POST 'https://api.zise.com/v1/transfers' \
  -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 '{
    "asset": "USDT",
    "recipient_type": "uid",
    "recipient": "10023481",
    "amount": "120.000000",
    "memo": "房租"
  }'

const res = await fetch(
  "https://api.zise.com/v1/transfers",
  {
    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({
      "asset": "USDT",
      "recipient_type": "uid",
      "recipient": "10023481",
      "amount": "120.000000",
      "memo": "房租"
    }),
  },
);
// 金额一律按字符串读，不要 JSON.parse 成 number
const data = await res.json();

import requests

res = requests.post(
    "https://api.zise.com/v1/transfers",
    headers={
        "authorization": "Bearer $TOKEN",
        "x-zise-merchant": "$MERCHANT_ID",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$(uuidgen)",
        "content-type": "application/json"
    },
    json={
        "asset": "USDT",
        "recipient_type": "uid",
        "recipient": "10023481",
        "amount": "120.000000",
        "memo": "房租"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()

发起站内转账（一步到账，没有待审态）

前置条件

请求头

请求体

响应