API 文档与开发者指南

快速接入

在站点上接收加密支付只需三步：创建 API 密钥、登记收款钱包地址、开出第一笔订单。由于全程非托管，收款资金直接进入由您控制的钱包。

• POST /v1/merchants/{merchant_id}/api-keys — 生成用于签名请求的 API 密钥对。
• POST /v1/addresses — 登记 USDT 等代币收款所用的固定钱包地址（每个网络与资产各一个）。
• POST /v1/sweep-addresses — 登记 TRX、BNB、GRAM 等原生币收款归集的主钱包。
• POST /v1/webhooks — 登记付款完成时接收通知的 URL 接口。

请求签名（HMAC）

所有 HTTP 请求均使用 HMAC-SHA256 签名。签名基于请求的原始报文体（raw bytes）计算，因此即使 JSON 字段顺序发生变化，签名依然有效。

METHOD \n PATH \n TIMESTAMP \n NONCE \n SHA256(raw_body)

X-Api-Key

API 密钥 ID（pk_…）

X-Timestamp

Unix 时间戳（秒，允许服务器时钟容差）

X-Nonce

唯一随机字符串（最长 128 字符，一次性）

X-Signature

hex(hmac_sha256(secret, canonical))

请求安全由两层保障：时间戳须落在容差窗口内，且每个 nonce 仅可使用一次。重复提交同一请求会被自动拒绝（HTTP 401）。

1import hashlib, hmac, os, time, json, urllib.request
2 
3KEY_ID  = os.environ["COINZEN_KEY_ID"]
4SECRET  = os.environ["COINZEN_SECRET"]
5BASE    = "https://coinzen.cerceyn.com"
6 
7def request(method: str, path: str, payload: dict | None = None) -> bytes:
8    body = json.dumps(payload).encode() if payload is not None else b""
9    ts = str(int(time.time()))
10    nonce = os.urandom(16).hex()
11    canonical = "\n".join(
12        [method.upper(), path, ts, nonce, hashlib.sha256(body).hexdigest()]
13    )
14    signature = hmac.new(SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
15 
16    req = urllib.request.Request(
17        BASE + path,
18        data=body or None,
19        method=method.upper(),
20        headers={
21            "X-Api-Key": KEY_ID,
22            "X-Timestamp": ts,
23            "X-Nonce": nonce,
24            "X-Signature": signature,
25            "Content-Type": "application/json",
26        },
27    )
28    with urllib.request.urlopen(req) as resp:
29        return resp.read()

订单生命周期

创建订单后即进入状态机。若未指定网络与资产，订单以 selecting 状态开始。客户在支付页面选定网络与币种后，订单转入 pending 并分配收款地址。

• selecting → pending, expired, cancelled
• pending → confirming, partially_paid, expired, cancelled
• confirming → paid, overpaid, failed
• paid ⇄ overpaid — 若客户对已付订单再次转账，金额会自动更新。

paid、overpaid、expired、cancelled 与 failed 为终态。遇到链上重组或迟到付款时，系统会自动更新状态并通过回调通知您的系统。

回调通知

订单状态的每次变化都会推送到您登记的回调接口。每个数据包均使用 HMAC-SHA256 签名，您可据此确认数据完整且确实来自 Coinzen。

X-Coinzen-Signature

t=<unix>,v1=<hex hmac_sha256(secret, "<t>.<raw_body>")>

X-Coinzen-Delivery

唯一投递 ID（UUID）

X-Coinzen-Event

触发的事件名称（例如 invoice.paid）

1import hashlib, hmac, time
2 
3def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
4    """X-Coinzen-Signature: t=<unix>,v1=<hex>"""
5    parts = dict(p.split("=", 1) for p in header.split(","))
6    t, v1 = parts["t"], parts["v1"]
7    if abs(time.time() - int(t)) > tolerance:
8        return False
9    expected = hmac.new(
10        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
11    ).hexdigest()
12    return hmac.compare_digest(expected, v1)

支持的回调事件

• invoice.pending
• invoice.confirming
• invoice.partially_paid
• invoice.paid
• invoice.overpaid
• invoice.expired
• invoice.cancelled
• payment.reverted
• deposit.unmatched
• credit.low
• credit.exhausted

自动重试机制

首次投递在付款完成后立即进行。若您的服务器未返回 200 OK，系统会按 30 · 120 · 600 · 3600 · 21600 · 86400 秒的间隔分七级自动重试。全部重试失败后，记录转入 dead_letter 状态，可在控制台一键重新入队。

手续费与服务余额

Coinzen 从不从客户付款中扣取手续费。USDT 及其他加密货币付款直接进入您的地址，该钱包的私钥仅由您持有。平台服务费从您预先充值的服务余额中扣减，因此收款始终足额。

• 标准费率为 1%。新开通账户前 45 天适用 0.1% 的优惠费率。当前适用费率可在 GET /v1/credit 响应的 fee_bps 字段查看（基点：10 = 0.1%，100 = 1%）。
• 仅对成功完成的订单（paid 与 overpaid）收取手续费。
• 已取消、已过期或金额不足的订单不收取任何手续费。
• 服务余额用尽时，已开订单的收款流程不受影响，正常处理；仅新建订单的请求会收到余额提示（HTTP 402）。

两步扣费模型

订单付款完成时，手续费记录立即以 pending 状态创建，不依赖任何外部服务，以免拖慢链上跟踪速度。汇率换算在后台完成后，净额从余额中扣减。

若发生链上重组导致付款回退，手续费扣减会立即作废；若已扣减，则以 reversal 记录退回余额。

服务余额充值

调用 POST /v1/credit/deposit-addresses 可获得专属的 USDT 长期充值地址。向该地址转入的资金在链上确认后即自动计入服务余额，无需人工审核或等待。

自动补足

启用后，即使服务余额归零，您的销售也不会中断。系统会将下一笔小额订单的收款直接转入服务余额，服务持续可用。

• 转入服务余额的该笔订单不再另行收取手续费。
• 出于安全考虑设有上限（默认 25 USD）。超过上限的订单不会被转入，大额订单不受影响。
• 可随时通过 PUT /v1/credit/auto 接口或控制台启停，并自行设定上限。

余额提醒

服务余额低于阈值时触发 credit.low 事件，用尽时触发 credit.exhausted，让您提前知悉。

支持的区块链网络与资产

下表为正式网络注册表的摘要。如需运行时的实时清单，请调用 GET /v1/networks。

API 接口