DEVELOPER GUIDE · V1
接入 CF Pay
分配地址,验证链上入款,将确认结果交给你的账本。
一套核心,两种接入方式
| 方式 | 适用情况 | 入账边界 |
|---|---|---|
| 嵌入式组件 | Django 产品内置核心;CF GAME 使用此方式 | 通过宿主适配器,在同一数据库事务内记账 |
| 独立服务 | 其他技术栈通过服务端 API 接入 | 读取通知、幂等记账、再确认通知;两个系统各自持有事务 |
独立服务管理接入方、客户引用和链上事件。每个接入方只能查询自己名下的记录。一个客户在一条链上共用一个固定地址,不按币种或充值次数重新分配。
快速开始
- 由运营方开通接入账号,登录控制台,生成 API 密钥。
- 服务端查询可用资产,选择对应网络与币种。
- 用你系统中的客户编号申请充值地址,并向用户显示币种、网络和地址。
- 轮询待处理通知;你的系统成功提交账本后,再确认通知。
以下命令中的服务地址和密钥由你的服务端环境提供。密钥不得放到浏览器。
curl "$CF_PAY_URL/api/v1/assets/" \
-H "Authorization: Bearer $CF_PAY_KEY"
curl "$CF_PAY_URL/api/v1/addresses/" \
-H "Authorization: Bearer $CF_PAY_KEY" \
-H "Content-Type: application/json" \
-d '{"customer_ref":"customer-001","asset_id":1}'asset_id 必须使用资产列表返回的编号。相同接入方、客户编号和网络重复请求,返回相同地址。当前资产列表为空时,表示没有可开放的充值通道。
API 参考
所有接口使用 Authorization: Bearer <密钥>,返回 JSON。金额使用字符串,不能转成浮点数。
| 接口 | 用途 |
|---|---|
GET /api/v1/assets/ | 当前可用资产、合约、精度、确认门槛 |
POST /api/v1/addresses/ | 按 customer_ref、asset_id 分配固定地址 |
GET /api/v1/deposits/ | 历史事件;支持 customer_ref、before_id、limit |
GET /api/v1/notifications/ | 读取未确认接收的通知;limit 为 1–100 |
POST /api/v1/notifications/{id}/ack/ | 确认已处理,允许重复调用 |
历史记录按编号倒序分页;使用返回的 next_before_id。通知按编号正序读取,未确认接收的通知会再次返回。
错误:400 请求格式错误;401 密钥无效或账号停用;404 记录不存在或不属于当前接入方;405 方法错误;503 入款服务暂不可用。503 可退避重试,不能据此给用户加余额。
到账通知与宿主入账
{
"id": 42,
"version": 1,
"type": "deposit.confirmed",
"event_id": 18,
"customer_ref": "customer-001",
"network": "ethereum",
"symbol": "USDT",
"atomic_amount": "100123456",
"decimals": 6,
"amount": "100.123456",
"ledger_amount": "100.12",
"confirmations_required": 64,
"finality_verified": true
}这是字段示例,真实通知还包含收款地址、代币合约、交易哈希、事件索引、区块高度和哈希。ledger_amount 按币额 1:1、向下截断到两位,不提供汇率换算。
- 校验通知类型、网络和合约是否符合你的接入配置。
- 使用“服务实例 + 接入方 + event_id”建立唯一入账约束。
- 在同一事务内写入处理记录并更新你的账本。已处理的事件不得再次加余额。
- 账本事务提交后调用 ack;请求失败时重试,不重新记账。
deposit.review 表示已确认事件发生链上重组,系统暂停该网络。应交由运营核查,不自动扣减客户余额。通知支持至少一次交付,不声称跨系统恰好一次入账。当前独立服务使用轮询与确认机制,不向接入方推送 HTTP 回调。
状态与金额精度
| 状态 | 含义 |
|---|---|
| confirming | 等待确认数或区块最终性 |
| confirmed | 链上核验通过,已生成到账通知;宿主余额以自己的账本为准 |
| held | 暂停接入、账户停用或其他限制,需处理后重新核验 |
| dust | 向下截断到两位后为零,不生成加余额通知 |
| orphaned | 未确认事件已不在有效链上 |
| review | 已确认事件发生重组,进入核查 |
原子金额完整保留为字符串,支持 uint256。只有确认数达到配置门槛,并且 Ethereum finalized 或 TRON solidified 校验通过,才产生确认通知。独立站最低门槛为 64。
运行与责任边界
运营方可在内部控制页按链分别启停自行扫链、第三方监控总开关和各个供应商。QuickNode 与 Alchemy 可同时启用;只有运营账号能够修改。仅第三方模式保留回执核验与确认门槛,但没有区块遍历兜底,重新开启扫链后从保留游标补扫。
初次启动默认关闭充值、主网及供应商写操作。启动网站不会启动监听器。运营方必须配置独立数据库、HTTPS、公开派生分支、可信 RPC,以及明确的起始扫描高度;再完成只读预检与补扫。
在线应用不保存私钥或助记词,不签名、不广播。运营方的钱包体系控制收款资金;第三方 RPC / 通知服务只提供数据。归集只生成离线指令并核验归集结果。本组件不提供用户提现。
包内 README 和 deployment 文档包含独立安装、嵌入钩子与部署步骤。CF Pay 核心可以单独交付,无需复制 CF GAME 的用户或资金数据库。