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

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

会触发的事件

transfer.completed

绿 = 终局且是好消息 · 红 = 终局且要处置 · 紫 = 中间态。点进去看事件体与验签。

请求

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

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

import requests

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

req, _ := http.NewRequest("POST", "https://api.zise.com/v1/transfers",
    strings.NewReader(`{
  "asset": "USDT",
  "recipient_type": "uid",
  "recipient": "10023481",
  "amount": "120.000000",
  "memo": "房租"
}`))
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/transfers"))
    .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("""
{
  "asset": "USDT",
  "recipient_type": "uid",
  "recipient": "10023481",
  "amount": "120.000000",
  "memo": "房租"
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double

$ch = curl_init('https://api.zise.com/v1/transfers');
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'
{
  "asset": "USDT",
  "recipient_type": "uid",
  "recipient": "10023481",
  "amount": "120.000000",
  "memo": "房租"
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval

200

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

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

前置条件

请求头

请求体

响应

会触发的事件