API 参考 › 入金

上报会员入金

POST /v1/deposits scope: deposits:write

代会员调用 · 必带 x-on-behalf-of 需 x-idempotency-key 动钱 · 增会员 available，同额增 merchant.custody（我方替你记的负债）

这个端点会动钱

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

全系统唯一一个凭空产生会员余额的端点。 六道闸一道都不能省：

1. 强制签名 —— 即便这把 Key 配了 signature_required=false，

此端点仍强制。少了 x-signature / x-timestamp / x-nonce

一律 401，且时间戳容差 ±300 秒、nonce 不可重放；

2. 幂等键必须带租户前缀且由商户提供业务流水号（reference）——

重复上报同一笔链上入金 = 双倍记账；

3. 单笔与日累计上限（按商户配，总后台设）；

4. 资产必须在该商户的白名单内，认不出的一律拒绝而不是挂账；

5. 照常过平台风控与准入 —— 上报入金不等于绕开风控；

6. 全量审计 + 商户后台可见。

凭证是两条腿：member.available credit W / merchant.custody debit W。

merchant.available 不参与 —— 上报入金不是一笔成本。

两把键，别混

x-idempotency-key（请求头，UUID）挡的是你的网络重试：

同键同体 24 小时内原样回放首次结果，同键异体 409。

reference（请求体）挡的是同一笔链上入金被上报两次：

它进的是账本幂等键 mdep:<商户>:<reference>，

和你换没换幂等键无关。所以 reference 必须是你那边那笔

链上交易的稳定标识（txid + vout、或你自己的入金单号），

不许每次调用现生成一个。

重复命中时返回 200 + replayed: true，首次成功是 201。

replayed 这一位让你不用去比对余额就知道「这笔我方早就记过了」。

链上溯源：四个可选字段，传了就存得住

network / txid / from_address / to_address 是这笔钱的来源证明。

我方在 merchant_hosted 下不观测链，所以这几样只能由你给——

不给的话，这笔凭空产生的会员余额在我方账本上唯一的线索就是你那串

reference。三种场景会当场卡住：会员说没充而你说充了（我方站在中间

无法自证任何一边）、监管问询这笔资金来源（我方拿不出 txid）、

需要给这笔入金挂一个发起方地址（没有 from_address 可挂）。

四个都可选 —— 线下入金（收法币、内部划转）确实没有这些；
但有 txid / 任一地址就必须有 network，否则 400

invalid_fields。不知道在哪条链上的 txid 与没有 txid 等价：

查不了浏览器、答不了问询，而它在界面上看着像"有溯源"。

同一串 0x… 在 BSC / ETH / Polygon 上是三个不同的账户；

network 不做白名单 —— 这一跳的链是你自己的收款基础设施，

我方拿一张自己的链目录去卡它，等于我方每上一条新链之前你都无法

如实申报。自动转大写；

同一个 reference 重复上报时，链上字段与金额同一条纪律：

首次那份为准，第二次传的不会覆盖。响应里回显的是**库里存着的

那一份**，不是你这次传的 —— 照入参回显会让你以为新 txid 被接受了。

⚠ txid 不去重、也不该去重。 一条链上交易可以承载多笔入金

（UTXO 的多个 vout、ERC-20 批量转账、交易所归集）。去重的依据始终是

reference。

白名单的语义

一行都没配 = 该商户尚未启用白名单，按平台资产目录放行。

一旦配了任意一行，就必须逐资产命中且启用 —— 没有那一行的资产

是拒绝，不是「没配限额」。

失败之后怎么办

收到 504 / 网络超时：用同一把 x-idempotency-key 重试，

我方可能已经记过了；

收到明确的 4xx：换新键重试，同键会把那次失败原样回放给你；
收到 limit_exceeded：看 limit_type（single 单笔 / daily

日累计），这不是重试能解决的，去商户后台看额度。

前置条件

请求已签名（此端点强制，不受 Key 的 signature_required 影响）
资产在平台目录内且已启用；若该商户配了白名单，还必须逐资产命中且启用
会员未被封禁 / 拉黑 / 冻结（照常过平台准入）

字段	类型	必填	说明
`x-on-behalf-of`	string	必填	给哪个会员记这笔入金
`x-idempotency-key`	string	必填	UUID。格式不对直接 400 `idempotency_key_invalid`。
`x-signature`	string	必填	HMAC 签名。此端点不可关闭签名，与 Key 上的 `signature_required` 配置无关。
`x-timestamp`	string	必填	Unix 秒。容差 ±300 秒，超窗回 `timestamp_out_of_range`。
`x-nonce`	string	必填	一次性随机串。重放窗口内重复使用回 `nonce_reused`。

请求体

字段	类型	必填	说明
`asset`	string	必填	资产代码。我方会自动转成大写，所以 `usdt` 与 `USDT` 等价。不在目录/白名单内一律 `asset_not_allowed`。
`amount`	string	必填	入账数量，必须 > 0。字符串定点，位数 = 该资产 `ledger_scale`。小数位多于 scale 且尾数非全 0 时直接 400 —— 我方不做四舍五入，宁可让你自己决定。USDT（ledger_scale=6）形如 1500.000000
`reference`	string	必填	你那边这笔入金的稳定业务流水号，≤ 120 字符。它进账本幂等键，是「同一笔钱只入账一次」的唯一依据。 ⚠ 每次调用现生成一个 = 这道闸完全失效。 ⚠ 它同时是 `GET /v1/deposits/{id}` 的路径参数。含 `/` 的流水号请改用 `GET /v1/deposits?reference=` —— 斜杠在路径里是分段符，转义也不可靠。
`network`	string	可选	链上网络机读码，如 `BSC` / `TRON` / `ETH`。可选，自动转大写，≤ 32 字符，我方不做白名单校验。 ⚠ 传了 `txid` 或任一地址时必填。
`txid`	string	可选	链上交易哈希，≤ 128 字符。可选。多笔入金共用一个 txid 是允许的（UTXO 的多个 vout、批量转账）。
`from_address`	string	可选	发起方地址（这笔钱是从哪儿来的），≤ 200 字符。可选。这是"入金来源地址"那件事在我方模型下的落点 —— 我方不另设登记接口，因为它天生属于这一笔入金。
`to_address`	string	可选	你这一侧的收款地址，≤ 200 字符。可选。

响应

200幂等命中 —— 这笔我方早就记过了，本次没有再记一遍。链上四个字段回的是库里存着的那一份（首次那次传的），不是你本次传的。

{
  "id": "dep_0xa3f1c2e9-0",
  "reference": "0xa3f1c2e9-0",
  "external_member_id": "u_10023",
  "asset": "USDT",
  "amount": "1500.000000",
  "ledger_scale": 6,
  "status": "credited",
  "network": "BSC",
  "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
  "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "replayed": true
}

201已入账（首次）

{
  "id": "dep_0xa3f1c2e9-0",
  "reference": "0xa3f1c2e9-0",
  "external_member_id": "u_10023",
  "asset": "USDT",
  "amount": "1500.000000",
  "ledger_scale": 6,
  "status": "credited",
  "network": "BSC",
  "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
  "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "replayed": false
}

400invalid_request 缺字段 / 金额非法 / reference 超 120 字符 · invalid_fields 链上字段超长，或给了 txid/地址却没给 network · asset_not_allowed 资产不在目录或不在该商户白名单内 · limit_exceeded 超限（看 limit_type = single 或 daily， limit_scope = merchant） · request_rejected 会员被平台准入拦下（不下发原因） · insufficient_balance 过账时余额类 CHECK 被撞 · idempotency_key_required / idempotency_key_invalid 幂等键问题

401signature_required 没带签名 · invalid_signature 签名不匹配 · timestamp_out_of_range 时间戳超窗 · nonce_reused nonce 重放

409idempotency_key_reused 同一把幂等键配了不同的请求体 · idempotency_in_progress 首次请求还在处理中，稍后同键重试

请求

curl -X POST 'https://api.zise.com/v1/deposits' \
  -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",
    "amount": "1500.000000",
    "reference": "0xa3f1c2e9-0",
    "network": "BSC",
    "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
    "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
    "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
  }'

const res = await fetch("https://api.zise.com/v1/deposits", {
  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",
    "amount": "1500.000000",
    "reference": "0xa3f1c2e9-0",
    "network": "BSC",
    "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
    "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
    "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();

import requests

res = requests.post(
    "https://api.zise.com/v1/deposits",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={
      "asset": "USDT",
      "amount": "1500.000000",
      "reference": "0xa3f1c2e9-0",
      "network": "BSC",
      "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
      "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
      "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()

req, _ := http.NewRequest("POST", "https://api.zise.com/v1/deposits",
    strings.NewReader(`{
  "asset": "USDT",
  "amount": "1500.000000",
  "reference": "0xa3f1c2e9-0",
  "network": "BSC",
  "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
  "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}`))
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/deposits"))
    .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",
  "amount": "1500.000000",
  "reference": "0xa3f1c2e9-0",
  "network": "BSC",
  "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
  "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double

$ch = curl_init('https://api.zise.com/v1/deposits');
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",
  "amount": "1500.000000",
  "reference": "0xa3f1c2e9-0",
  "network": "BSC",
  "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
  "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval

200

{
  "id": "dep_0xa3f1c2e9-0",
  "reference": "0xa3f1c2e9-0",
  "external_member_id": "u_10023",
  "asset": "USDT",
  "amount": "1500.000000",
  "ledger_scale": 6,
  "status": "credited",
  "network": "BSC",
  "txid": "0xa3f1c2b7d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f",
  "from_address": "0x9C3f1B7a5E2d4C6b8A0f2E4d6C8b0A2f4E6d8C0b",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "replayed": true
}

上报会员入金

前置条件

请求头

请求体

响应