API 文档与开发者指南

快速接入

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

• 控制面板 → API 密钥 — 登录后在此生成密钥对（KeyId 与 Secret）。Secret 仅在生成时显示一次。
• 面板 → 设置或 POST /v1/static-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）。

X-Timestamp 为 Unix 时间戳（秒），与服务器时间的偏差不得超过 300 秒。X-Nonce 每次请求唯一；已使用的 nonce 在 600 秒 内会被拒绝。

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()

权限范围

每个密钥只能调用其被授予权限范围内的接口；缺少权限时返回 403。权限范围在面板中生成密钥时选择。

频率限制

限制按商户计算，采用一分钟滑动窗口。超出时返回 429 并附带 Retry-After 响应头。

• 常规接口 — 120 次请求 / 分钟
• 创建订单 — 30 次请求 / 分钟

幂等性

调用 POST /v1/invoices 时必须携带 Idempotency-Key 请求头；缺失时返回 422。每次请求都应生成新的唯一值。

Idempotency-Key: 7f3c1e9a4b8d42f0a1c6e5b3d9074a2e

使用相同密钥重发相同请求体不会创建第二个订单：系统原样返回首次响应及其状态码。网络中断后可安全重试。

订单生命周期

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

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

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

余额支付

若您销售余额或储值，固定金额并不合适：付款方会把 5.188 抹零成 5，订单便金额不足。使用 balance_payment: true 开具订单后，实际到账即可结清订单——显示金额仅为建议，支付页也会明确告知付款方。

请依据 webhook 中的 received_amount 以及按锁定汇率计算的 received_fiat_amount 入账，而非 fiat_amount。即使订单要求 250 TRY，到账 5 USDT 时应入账的就是这 5 USDT 的价值。手续费同样按到账金额计提。

代币收款的地址是共享的，把付款与订单绑定的是金额。若同一网络／资产上同时有多笔余额订单，抹零后的付款无法归属；系统不作猜测——款项进入未匹配入账并触发 deposit.unmatched webhook。您可在面板中将其关联到正确订单。不能与储值订单同时使用。

回调通知

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

用于验证签名的 Webhook Secret（whsec_…）仅在登记回调接口时发放一次：可在控制台的回调页面获取，或从 POST /v1/webhooks 响应的 secret 字段获取。它不是 API 密钥的 Secret；后者仅用于为您发出的请求签名。重新登记同一地址会发放新的 Webhook Secret，并停用旧记录。

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 状态，可在控制台一键重新入队。

错误契约

所有错误使用统一结构。code 字段稳定，供程序判断；message 面向人阅读，内容可能变化。

1{
2  "error": {
3    "code": "conflict",
4    "subcode": "order_id_exists",
5    "message": "bu order_id zaten kullanılmış",
6    "details": { "order_id": "A-1042" }
7  }
8}

subcode 字段用于细化类别码，例如以 order_id_exists 代替 conflict。请先读取 subcode，没有时回退到 code——该契约只会扩展，不会收窄。

请求未通过结构校验时（缺少字段、类型错误、数值超出范围），code 为 validation_error，details 将字段路径映射到错误类型：{"body.url": "url_scheme"}。类型用于程序匹配（如 missing、greater_than），说明文字位于 message。

手续费与服务余额

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 接口

请求结构

以下是接入首日会调用的接口请求体。全部接口的完整结构以机器可读格式发布在 GET /openapi.json，可导入 Postman 或用于生成客户端代码。

查询参数