加密支付 API：好 API 长什么样，外加一份能在浏览器里跑完的走查

先给答案：一个生产级的加密支付 API，需要的恰好是五样东西——一笔付款一个专属地址（对账从构造上成立）、诚实的状态机（让你永远不会在"看见了"而非"结算了"时发货）、带签名且会重试的 webhook（让发货流程扛得住你服务器的糟糕一天）、游标分页（让十万订单的对账不是一次超时）、能发真 webhook 的沙盒（让你在钱动之前排练完一切）。这篇沿着 Finality 的 API 把五样逐个走查，还有一个大多数文档埋起来的细节：下面每个请求，都能先在浏览器里、在 API 测试台发出去——一行集成代码都不用写。

性质一：一笔付款，一个地址

建单就是一个 POST:

curl -X POST https://finality.money/v1/intents \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "solana",
    "token": "USDC",
    "amount": "129.00",
    "merchant_order_id": "ORD-2201"
  }'

返回一个绑定 ORD-2201 的专属收款地址（外加托管收银台 URL 和二维码内容）。这一个设计决定，悄悄删掉了三个经典的集成头疼：不用按金额猜单（到这个地址的就是这一单的），没有顾客会忘填的 memo 字段，而且交易所提现直接成为有效付款——从币安直付的顾客不需要任何钱包，这比其他任何收银功能都重要。地址还在派生里携带自己的结算规则：固定 1% 和你的收款钱包在生成那一刻焊死，谁都改不了。

性质二：诚实的状态机

Finality 把一笔付款的一生建模为恰好八个状态：created、awaiting_currency、pending、detected、confirmed、settled、expired、failed。由此落下两条集成规则：

• 只在 settled 上发货，其余一概不。detected 的意思是"区块里存在一笔转账"——看见钱不等于拿到钱。状态之所以分开，是因为混同的代价是真实的货。
• 查"已付但未终局"用 detected,confirmed。这个 API 从不吐出一个含糊的"处理中"——每个状态都是一个可以分支判断的事实。

少付会带着差额浮出来（订单保持开放，顾客往同一地址补齐）；迟到的钱被标记且可回收，不是被静默吞掉。把边缘情况藏起来的 API 并没有消灭它们——只是把它们变成了你的客服工单。

性质三：按最坏情况设计的 webhook

结算完成时，带签名的 payment.settled 打到你的端点——HMAC 签的是原始字节，你宕机时最多重试 16 次并退避，需要重新驱动处理逻辑时还能从控制台重放。十七种事件覆盖整个生命周期（包括 payment.partial 和 payment.blocked——这些是你想"被通知"而不是"自己发现"的事）。

验签只有三个值得专门设防的 bug——先解析再验签、不安全比较、缺幂等——完整代码版在把支付 webhook 做对。这里只说 API 设计层的点："至少一次投递"加上你的幂等键，这份契约让"我服务器挂了一小时"变成一件无事发生的事。

性质四：翻到第一万页也不虚的对账

日常对账是一次批量查询，不是循环单查：

GET /v1/orders?period=7d&status=settled&limit=500

过滤覆盖时间窗、状态集，以及跨订单号、收款地址、交易哈希的子串搜索。分页是按 (created_at, id) 排序的 keyset（游标）分页——没有 OFFSET，第一万页和第一页一个价，扫描中途新来的订单也不会造成重复或空洞。文档里明写的两个诚实怪癖（因为在生产里自己发现会更疼）：两个游标字段必须一起回传——只发一个会被静默忽略，你会重新拿到第一页；stats 块刻意不理会你的过滤条件（它回答"账户怎么样"，不回答"这批筛选结果的合计"——合计请自己对列表求和）。

API 赢得信任的地方恰恰在这：不在顺利路径，而在把自己的棱角写清楚。

性质五：能排练一切的沙盒

换上 sk_test_ 密钥，整台机器零真钱运转：建单、打开托管收银台、点模拟支付，一条真 webhook——生产格式、真实签名——打到你的端点。重放它测幂等；少付一点看 payment.partial。从排练到上线，只是换一个密钥。

这也是 API 测试台配得上本文标题的地方：上面每个接口都能在浏览器里执行——真请求、活响应、不用配 Postman——把"评估这个 API"从一下午压缩到十五分钟。

刻意缺席的东西

三样你找不到的东西，每一样都是故意的：

• 没有私钥操作。这个 API 从不索取、存储或接触任何控制资金的私钥。收款钱包只作为目的地配置一次；结算发生在链上，不经过我们运营的账户。
• 没有余额和提现接口——因为不存在平台余额。哪个 API 里有 withdraw 调用，你读的就是一份托管方的 API。
• 没有卡式 tokenization——流程里不存在卡数据，自然没有要保险柜的东西。

支付之外：别家没有的那部分接口面

因为订阅和分销结算活在链上，这个 API 的边界延伸到了竞品到不了的地方：订阅计划与顾客自控金库（架构）、佣金在顾客付款交易内部切分的分销链接，以及面向 AI 代理买家的机器支付(x402)。一把 API 密钥，整个收入栈。

FAQ

基础集成要多久？

收银时一个 POST，加一个带验签和幂等键的 webhook 处理器。多数团队一下午交付；沙盒让排练免费。

有 SDK 还是裸 REST?

干净的 REST + JSON——上面那段 curl 就是全部形状。文档有逐接口参考；测试台在浏览器里给你活例子。

失败路径怎么测？

沙盒：模拟、少付、重放 webhook、让报价过期。每条难看的路径都能零真钱排练——而那正是你该见到它们的时候。

该按什么限额设计？

对账查询的 limit 上限 5000，配游标翻页——批量拉取被设计得很便宜。建单对你的 merchant_order_id 幂等，重试天生安全。

有免费测试加密支付 API 的方式吗？

沙盒免费且完整：测试密钥、模拟支付、真 webhook——在真钱存在之前排练完一切。

怎么把加密支付 API 集成进我的应用？

收银时一个 POST，加一个带验签和幂等键的 webhook 处理器——上面那五个性质就是全部集成面。多数团队一个下午交付。

对开发者来说，好的加密支付 API 长什么样？

就是这篇文章跑的那五个性质：专属地址、诚实状态机、带签名会重试的 webhook、游标分页、发生产格式事件的沙盒。功能清单各家不同；决定生产行为的是这五条。

这套 API 支持循环扣款吗？

支持——订阅套餐与顾客金库就在同一套 API 上：建套餐、发收银链接、处理两个生命周期 webhook。

AI 代理能调这套 API 吗？

整条流程没有一步预设人类——专属地址加普通转账意味着代理付款人今天就能用,x402 式的按请求计费走的也是同一条结算轨道。

有哪些语言的 SDK?

API 是刻意的纯 REST+JSON——上面那段 curl 就是全部形状，所以每种语言的 HTTP 客户端都是 SDK。验签示例在文档里。

评判一个 API 最快的方式是调用它：打开 API 测试台，发一笔沙盒建单，看状态机走起来——没有注册表演，没有演示视频，只有真机器回答真请求。