Zise Developers

Zise 资产 API

余额、流水、入金上报提现扣账

托管模型(必读)

外部商户一律 merchant_hosted会员资金由商户自己托管

链上收付我方一概不碰。我方负责按商户的声明记账、执行平台风控与准入、

扣商户预付账户里的业务成本。

由此推出这两条与直觉相反的事:

POST /v1/deposits 让会员余额增加。

(available → withdrawing),商户完成链上出款后调 confirm

没有 dispatch_unknown 这一档:发起链上交易的不是我方。

金额约定

一律字符串定点,位数 = 该资产 ledger_scale;响应同时下发

ledger_scaledisplay_scale

⚠ BSC 18 位小数超 2^53,用 JSON number 解析即精度事故。

端点

GET/v1/balances
会员逐资产余额(八桶)
Scope balances:read · 作用域 会员(需 x-on-behalf-of)
GET/v1/transactions
会员流水(游标分页)
Scope balances:read · 作用域 会员(需 x-on-behalf-of)
POST/v1/deposits
上报会员入金

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

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

此端点仍强制;

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

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

3. 单笔与日累计上限(按商户配,总后台设);

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

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

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

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

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

Scope deposits:write · 作用域 会员(需 x-on-behalf-of)
GET/v1/deposits
入金记录(我方账本视角)
Scope deposits:read · 作用域 会员(需 x-on-behalf-of)
POST/v1/withdrawals
提现扣账(available → withdrawing)

此刻钱不可再用。merchant.custody 不动 —— 钱还在商户手上。

Scope withdrawals:write · 作用域 会员(需 x-on-behalf-of)
GET/v1/withdrawals/{id}
提现详情
Scope withdrawals:read · 作用域 商户
POST/v1/withdrawals/{id}/confirm
商户完成链上出款后确认

withdrawing 清零,merchant.custody 同额减少(商户欠会员的少了)。

Scope withdrawals:write · 作用域 商户
POST/v1/withdrawals/{id}/fail
上链失败,全额退回可用
Scope withdrawals:write · 作用域 商户