cf CF Pay

DEVELOPER GUIDE · V1

接入 CF Pay

分配地址,验证链上入款,将确认结果交给你的账本。

一套核心,两种接入方式

方式适用情况入账边界
嵌入式组件Django 产品内置核心;CF GAME 使用此方式通过宿主适配器,在同一数据库事务内记账
独立服务其他技术栈通过服务端 API 接入读取通知、幂等记账、再确认通知;两个系统各自持有事务

独立服务管理接入方、客户引用和链上事件。每个接入方只能查询自己名下的记录。一个客户在一条链上共用一个固定地址,不按币种或充值次数重新分配。

快速开始

  1. 由运营方开通接入账号,登录控制台,生成 API 密钥。
  2. 服务端查询可用资产,选择对应网络与币种。
  3. 用你系统中的客户编号申请充值地址,并向用户显示币种、网络和地址。
  4. 轮询待处理通知;你的系统成功提交账本后,再确认通知。

以下命令中的服务地址和密钥由你的服务端环境提供。密钥不得放到浏览器。

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、向下截断到两位,不提供汇率换算。

  1. 校验通知类型、网络和合约是否符合你的接入配置。
  2. 使用“服务实例 + 接入方 + event_id”建立唯一入账约束。
  3. 在同一事务内写入处理记录并更新你的账本。已处理的事件不得再次加余额。
  4. 账本事务提交后调用 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 的用户或资金数据库。