Z Zise Developers
/
API 参考 › 理财
POST /v1/earn/subscriptions

申购（活期余额包 / 定期一单一行）

Scope earn:write 代会员调用 · 必带 x-on-behalf-of 需 x-idempotency-key 动钱 · 会员可用余额 → 理财账户（同一名下重分类，两条腿自平）
这个端点会动钱

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

把会员的可用余额划进理财账户。钱始终在我方账本内，没有上游、

没有外部出口 —— 这是一次同一个会员名下的重分类。

两种产品的返回形状不同，由产品的 kind 决定，不是由你的入参决定：

  • 活期：id 前缀 ers_（一次申购操作），status 恒为 accruing；
  • 定期：id 前缀 ero_（一张订单），status 恒为 pending_start。

⚠⚠ 续期枚举是 principal_interest，不是 both。

这是这条线最容易踩的坑：我方会员端对认不出的值是**静默回落到产品

默认档** —— 用户选了「续本息」、界面也选中了、成交的却是别的档，

全程零提示。开放 API 上我方当场拒（invalid_request）：

你的配置写错了要立刻知道，而不是几个月后对账时发现。

合法值只有三个：none / principal / principal_interest。

⚠ rollover_mode 只对定期有意义，且**产品没开续期总闸时一律按

none 成交**（你传了也不认，且不会报错）。

⚠ 活期申购的起息时刻是「申购时刻 + 产品配置的 T+N」，不是成交

那一刻 —— 刚申购完查持仓，本金已经在里面但还没开始计息。

⚠ 这条线的失败形态是当场失败，不是排队：利率是在成交那一刻快照

的，一笔十分钟后才成交的申购比当场失败更糟。你的预付不足时会员看到

的是 service_unavailable，不解释原因。

前置条件

  • 产品对你开放、在售、在开售窗口内，且总额度与单人额度都还有余量
  • 会员满足产品的最低实名等级，账户未冻结 / 未销户
  • 会员该资产可用余额 ≥ amount
  • 你的预付账户在该资产上有足够余额
字段类型必填说明
x-on-behalf-of string 必填 代哪个会员申购。
x-idempotency-key string 必填 UUID。这把键同时是资金层的去重键：同键重放拿回上一次的结果， 不会申购第二次。

请求体

字段类型必填说明
product_id string 必填 产品 id。带不带 ern_ 前缀都认。
amount string 必填 申购金额。字符串定点，位数 = 该产品 ledger_scale。USDT 是 6 位，形如 1000.000000
rollover_mode "none" | "principal" | "principal_interest" 可选 到期处理方式，只对定期有意义。不传 = 用产品默认。 ⚠ 传 both 会被拒（invalid_request）—— 那个值不存在，正确写法是 principal_interest。

响应

201已受理。定期形如下例；活期返回的是 { id: "ers_…", kind: "flexible", status: "accruing" }。 ⚠ 响应里没有金额、没有起息日、没有到期日 —— 要这些请拿 GET /v1/earn/orders（定期）或 GET /v1/earn/positions（活期）回查。
{
  "id": "ero_c41d7f92-8a03-4bb6-9e10-5f2c8d3a7061",
  "kind": "fixed",
  "status": "pending_start"
}
400已登记的对外码：invalid_request 金额格式 / rollover_mode 不是 那三个值之一 · product_not_available 产品不存在或没对你开放 · limit_exceeded 产品总额度不足 · invalid_fields 金额 ≤ 0 或 量级越界 · request_rejected 会员被冻结 / 销户 / 拉黑 · service_unavailable 你的预付不足或理财线未对你开启 · 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/earn/subscriptions' \
  -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 '{
    "product_id": "ern_7d2b48ae-19c3-4f60-8c55-0ab3e9f21744",
    "amount": "1000.000000",
    "rollover_mode": "principal_interest"
  }'
const res = await fetch(
  "https://api.zise.com/v1/earn/subscriptions",
  {
    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({
      "product_id": "ern_7d2b48ae-19c3-4f60-8c55-0ab3e9f21744",
      "amount": "1000.000000",
      "rollover_mode": "principal_interest"
    }),
  },
);
// 金额一律按字符串读，不要 JSON.parse 成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/earn/subscriptions",
    headers={
        "authorization": "Bearer $TOKEN",
        "x-zise-merchant": "$MERCHANT_ID",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$(uuidgen)",
        "content-type": "application/json"
    },
    json={
        "product_id": "ern_7d2b48ae-19c3-4f60-8c55-0ab3e9f21744",
        "amount": "1000.000000",
        "rollover_mode": "principal_interest"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()