面向开发者的以太坊支付集成指南

以太坊支付的抽象等距标题图

以太坊支付集成是指在您自己的应用中接收 ETH 或代币。它包括为每位客户分配唯一地址、检测到账交易、判断何时视为最终到账，并与订单对账。您可以基于节点与 JSON-RPC 自行搭建，也可以调用处理钱包与通知的 API。

本指南同时介绍这两条路径，便于您在了解取舍的前提下做出选择。

要点速览

以太坊支付是一笔转移 ETH 或代币的已签名交易。提交交易并不等于确认到账，您必须检查回执。
首先确定收款范围：仅 ETH、稳定币与 ERC-20 代币，还是您自己的代币。这一选择决定了事件处理和 Gas 策略。
每个订单或每位用户使用一个充值地址，并通过 Webhook 接收事件，而不是轮询。
私钥、Webhook 签名和合约代码是三大主要安全面。
Chaingateway 等 API 可替代节点和区块扫描器，套餐起价为每月 €49。Gas 设置与确认策略仍由您自行决定。

什么是以太坊支付？

以太坊支付是来自某个账户的已签名指令，用于更新网络状态，例如转移 ETH 或代币。根据 ethereum.org 的交易文档，验证者随后会检查该交易，并将其打包进区块。只有在这之后，收款地址才真正收到资金。

这对您的应用有一个实际影响。客户并不是直接向您付款，而是向网络广播一笔交易，而您的系统必须察觉到它。集成中的所有工作，都是围绕这个“发现问题”展开的变体。

您会遇到两种付款：

原生 ETH 转账。交易本身包含收款方和金额，简单明了，可直接在交易及其回执中看到。
代币转账（ERC-20 及类似标准）。交易发送至代币合约，由合约在内部更新余额。该标准为此定义了 Transfer 事件，参见 ethereum.org 上的 ERC-20 规范。您的系统需从该事件日志中得知付款，而不是从交易自身的金额字段得知。

大多数稳定币结账属于第二种。如果您只监听 ETH 是否到达某个地址，就会漏掉它们。

写代码前应先决定什么？

您将接受哪些资产？

从能满足客户需求的最小范围开始。仅 ETH 最容易实现。加入稳定币可以消除价格波动，这对账单和订阅很重要。如果您发行自己的代币，还需要了解它的小数位数、合约地址，以及它是否符合标准 ERC-20。

每增加一种资产，就会多一个需要监控的合约地址、一个需要应用的小数位数值，以及一条定价规则。请保留一份小型白名单，并有意拒绝其他资产。

托管结账、付款链接还是 API？

集成方式有三种，它们在控制力与上线速度之间各有取舍：

方式	适用场景	您可控制的内容	您放弃的内容
托管结账或付款链接	快速上线、交易量小	流程几乎无法控制	品牌定制、资金托管、自定义逻辑
在自有前端中连接钱包	用户已持有 ETH 的去中心化应用	用户体验	检测与对账仍须自行完成
带钱包与 Webhook 的后端 API	应用、市场平台、SaaS 计费	地址、金额、订单逻辑	需要自行运维基础设施

如果您是在产品中构建支付功能的开发者，通常会选择第三种。选择任何服务商时可参考一份清单：是否提供沙箱环境、清晰的错误格式、有文档的速率限制，以及与您的技术栈相匹配的 Webhook。

资金托管与合规

谁持有密钥？如果您的平台为客户生成充值钱包，您就在经手资金。根据您所在的司法辖区和业务模式，这可能带来牌照或报告义务。请在上线前而非上线后，咨询熟悉您所在市场的律师。本指南讨论的是工程问题，不构成法律建议。

付款流程是怎样的，分哪几步？

以下是无论自建还是外购，在生产环境中都站得住脚的流程。

1. 创建付款请求

客户进入结账页面时，创建一条包含金额、资产和过期时间的订单记录。然后为该订单分配一个唯一的收款地址。每笔订单使用唯一地址，就能将到账转账与正确的客户匹配，而无需客户粘贴备注或参考号。

以稳定单位为订单定价。如果您接受波动性资产，则在短时间内锁定一个 ETH 金额，并保存这两个数字。

2. 客户签名并提交

如果客户通过浏览器钱包付款，您的前端会请求使用其账户的权限，构建交易对象并提交。MetaMask 的 eth_sendTransaction 参考描述了这一顺序：先获得账户授权，再提交交易，并保存返回的哈希。如果客户改从交易所或移动钱包向您展示的地址转账，您就看不到这一步，只能在链上看到结果。

无论哪种方式，交易哈希都是这笔付款的收据编号。请保存它。

3. 检测交易

发现付款有三种选择：

轮询。每隔几秒向节点查询回执或地址余额。简单，但浪费资源，规模扩大后也很脆弱。
订阅。与节点建立 WebSocket 连接，订阅新区块或合约日志。go-ethereum 关于实时事件的文档正是为此描述了 eth_subscribe。您必须自行处理断线，并重放遗漏的区块。
Webhook。服务监听链上动态，并在相关事件发生时调用您的服务器。这是维护成本最低的方式，也是大多数团队的选择。

对于代币，您要监听的是事件日志。以太坊文档指出，应用可以通过 JSON-RPC API 监听合约事件，并根据合约发出的日志采取行动。

4. 确认结果

提交不等于确认。MetaMask 发送交易指南展示了这一模式：按哈希轮询回执。没有回执说明交易仍在等待中；状态为 0x1 表示成功，0x0 表示失败。eth_getTransactionReceipt 参考补充说明，回执包含区块号、已用 Gas 和日志。

您的订单状态机应明确反映这一点：

awaiting_payment：已分配地址，尚未看到付款。
pending：已看到匹配的交易，但尚未打包进区块。
confirmed：找到回执，状态成功，金额与资产均匹配。
final：经过的后续区块数已达到您的风险容忍度。
failed、underpaid、overpaid 或 expired：需要明确规则处理的情况，不能置之不理。

放货前应等待多少个区块，是一项业务决策。几美元以内的数字商品可以在第一次确认后发货。高价值订单应等待更久，因为区块在网络最终确定之前偶尔会被重组。

5. 对账

每天将数据库中已确认付款的总额，与链上显示到达您地址的金额进行比对。任何差额都意味着存在缺陷、Webhook 漏送，或客户支付了错误的资产。ethereum.org 的数据与分析板块列出了可提供历史事件日志的索引服务，它们可以减少您需要自行维护的部分。

Gas、失败交易与退款如何运作？

很多首次集成的团队会在 Gas 上遇到意外。正如交易文档所述，每笔交易都要支付由基础费用和优先费用组成的手续费，并由发送方承担。这对您有三点影响。

客户可能付款不足或交易停滞。如果客户设置的费用过低，交易会一直处于待处理状态。在有效交易仍在途中时，订单不应过期。
失败的交易同样消耗 Gas。被回滚的代币转账会产生状态为失败的回执，客户的资金不会移动。不要因为看到了哈希就把订单标记为已付款。
从您这一侧发送会产生成本。退款、从充值地址归集到金库钱包以及付款，都需要 Gas；而转移代币时，代币地址同样需要 ETH。发送前请先估算手续费，并将其纳入预算。

在 Chaingateway API 中，gas、gasprice、maxFeePerGas 和 maxPriorityFeePerGas 是 ERC-20 与 ETH 交易端点的可选字段，GET /api/v2/ethereum/gasprice 返回当前的 Gas 价格。我们的指南如何估算以太坊及其他链上的 Gas 费用介绍了估算方法。

如果您希望客户完全无需持有 ETH 即可付款，账户抽象允许开发者代付交易费用，正如 ethereum.org 关于赞助 Gas 费用的教程所描述的。它会增加合约的复杂性，因此仅应在 Gas 门槛确实影响转化的产品中采用。

退款政策应事先确定。只有在确认退款地址不是您无法控制的交易所充值地址后，才退回至发送地址，或要求客户提供退款地址。网络费用可以明示扣除，也可以由您承担，但规则务必写明。

以太坊付款流程中 Gas、失败交易与退款的示意图

如何保护密钥、签名与合约？

私钥

持有密钥的人就控制着资金。请在加固的环境中生成密钥，切勿记录、切勿提交到代码库。将热钱包（余额较少，用于付款）与冷存储（保存大部分资金）分开。按计划将充值地址的资金归集到冷存储。

Webhook 真实性

Webhook 接收端是一个可以将订单标记为已付款的公开 URL，因此任何找到它的人都可以发送伪造事件。请从四个方面保护它：

对每个请求校验签名。HMAC 签名是常见做法。如果方案包含时间戳，应拒绝过期的请求。
让处理程序具备幂等性，使重复投递不会为同一订单入账两次。
在放货之前，通过直接查询核对金额和收款方。
如签名校验文章所述，Chaingateway 的 X-Signature 请求头只覆盖交易 ID，因此查询核对很重要。

智能合约代码

如果您自己编写付款合约，风险就转移到了代码上。以太坊官方安全报告指出，审计、经过测试的库、形式化验证与静态分析都能提升合约安全，而用于高级控制的自定义代码可能增加漏洞风险。实用原则是：当普通地址和标准代币事件足以满足需求时，不要部署自定义合约。

应自行构建还是使用 API？

自行构建的路径意味着运行或租用节点，并编写地址生成器。您还需要为所接受的每种代币编写日志解码器、估算 Gas、处理区块重组，并保持所有组件持续运行。对于产品本身就是支付基础设施的团队，这是合理的路径。

对于其他所有人，成本体现在时间和持续维护上。架构问题在于，是即时接收事件，还是之后批量对账。对于付款而言，即时接收事件是更好的默认选择。

我们的区块链 API 类型对比及适用场景介绍了各类别。以太坊概览则为初次接触该链的团队解释了 ETH、Gas 与 ERC-20 代币。

Chaingateway 如何融入以太坊集成？

Ethereum API 允许您通过 REST 发送 ERC-20 代币，无需 web3.js。三个端点即可覆盖大部分付款流程：

步骤	端点
创建充值地址	`POST /api/v2/ethereum/addresses`
监听该地址的 ETH 或代币到账	`POST /api/v2/ethereum/webhooks`，参数为 `to`、`url` 和 `type`（`ETH`、`ERC20` 或 `ERC721`）
向外发送 ETH 或 ERC-20 代币	`POST /api/v2/ethereum/transactions` 或 `.../transactions/erc20`

ERC-20 付款需要发送方、接收方、contractaddress 和 amount，对于由 API 创建时设置了密码的钱包，还需要钱包 password。手续费余额不足时，422 错误为 insufficient funds for gas * price + value。请先在 Sepolia 上使用请求头 X-Network: testnet 进行测试。Chaingateway Webhooks 页面和 Blockchain API 介绍了其他支持的网络，它们使用相同的调用方式。

失败的 Webhook 通知不会自动重试。使用 GET /api/v2/ethereum/webhooks/notifications/failed 列出它们，并逐一重发。

套餐按用量和功能计费：Plus 每月 €49，Pro 每月 €99，Premium 每月 €249，Enterprise 每月 €499；按年计费时分别为每年 €490、€990、€2,490 和 €4,990。每个套餐都提供 7 天免费试用，无需银行卡，也无需 KYC。各套餐包含的内容请参阅价格页面。

Chaingateway 首页截图：面向加密支付与 Webhook 的统一区块链 API，覆盖 7 条链

如何测试与监控以太坊支付集成？

演示能跑通，并不代表支付集成已经完成。请先在测试网上完成下列清单，再用小额真实资金重复一遍：

对 ETH 和每种已接受的代币，分别测试准确付款、少付和多付。
订单过期后的迟到付款，以及向同一地址重复付款。
使用过低 Gas 上限的失败交易，以便看到失败回执，并确认订单不会完成。
故意重放重复和乱序的 Webhook。
您自身的宕机：让服务器停机十分钟，发起一笔付款，然后重启，并确认没有任何数据丢失。
前端的钱包流程。QA 团队可以借助 ethereum.org 的 Impersonator.xyz 页面所列出的工具进行回归测试，而无需持有私钥。

上线后，应针对三个信号设置告警：在 pending 状态停留超过阈值的订单、数据库总额与链上总额之间的差额，以及 Webhook 投递失败。第一个信号能发现手续费问题，第二个能发现漏掉的事件，第三个能发现您自身的故障。

常见问题

接受付款一定要自行运行以太坊节点吗？

不一定。节点让您直接访问链，但您也需要承担其维护、同步和监控工作。大多数团队会使用服务商 API，或由服务替他们监听链上动态，并在付款到达时调用 Webhook。

如何确认到账的是代币付款，而不只是 ETH 付款？

监听代币合约中针对您收款地址的 Transfer 事件。该事件由 ERC-20 标准定义，代币转账不会在交易上以 ETH 金额的形式显示。Chaingateway 的 Webhook 通知直接包含发送方、接收方、合约地址和金额。

应等待多少个确认？

没有唯一正确的数字。它取决于订单金额，以及您对罕见链重组的容忍度。低价值的数字商品可以提前放货，高价值订单则应等待更久。请将阈值写入订单逻辑，避免客服逐案判断。

谁承担 Gas 费用？

由发送方承担。因此客户承担自己付款的费用，而您在发送退款、归集或付款时承担费用。通过账户抽象赞助的 Gas 可以在特定流程中把这部分成本转移给您。

同一套集成能否支持其他区块链？

如果您选择不与单一链绑定的接口，就可以。使用 Chaingateway，之后支持 Polygon 或 Arbitrum，只需在路径中换用不同的链名称，即可复用相同的钱包、转账和 Webhook 调用。Tron 采用类似的模式，但有其自己的手续费模型。