Polygon 支付集成：开发者指南与上线检查

一个钱包沿路径发送付款，连接到由区块相连而成的区块链

Polygon 支付集成，是让你的应用能够在 Polygon PoS 网络上接收和发送代币的一组组件：钱包、转账、验证和通知。你可以针对原始节点构建每个组件，也可以调用一个提供钱包、转账和 Webhook 的 REST API。本指南涵盖这两种方式。

TL;DR

Polygon PoS 的链 ID 为 137，使用 POL 支付 Gas。Amoy 测试网的链 ID 为 80002。
只有核对了交易状态、接收方、金额和代币合约之后，付款才算完成。仅凭哈希值不构成证明。
使用 Webhook 而非轮询来追踪付款。验证签名，并让处理程序具有幂等性。
Chaingateway 的 Webhook 不会自动重试，因此应与通知列表进行对账。
上线前而非上线后，就要规划法律范围、密钥托管、Nonce 冲突和 Gas 波动。

Polygon 支付集成包含哪些内容？

支付集成不仅仅是发送代币。一个可用的网关需要管理用户钱包、通过 Webhook 追踪每笔交易的状态，并在数据库中对余额进行对账。链只会告诉你发生了什么，而你的后端决定这对订单、发票或余额意味着什么。

实践中，你需要构建五个组件：

钱包层： 用于接收资金的地址，以及用于发送资金的密钥。
转账层： 构建、签名并广播代币转账的代码。
验证层： 检查转账是否确实按预期发生。
通知层： 向你的应用告知状态变化的 Webhook。
账本： 你自己的数据库记录，用于记录应付、已付和已结算的金额。

前四项属于链的底层管道。第五项才是你的产品。在管道上花的时间越少，你就能越快上线客户能看到的部分。

是否需要牌照？

在编写代码之前，先弄清楚你在哪里经营以及适用哪些规则。在欧盟，《加密资产市场法规》（MiCA）对加密资产服务提供商进行监管，详见 ESMA 的 MiCA 页面。在美国，FinCEN 的虚拟货币指南说明了在什么情况下，管理或兑换虚拟货币会使你成为货币转移商。

你的模式是否触发任何规则，取决于你是否代他人持有或转移资金。这个问题应由熟悉支付业务的律师回答，而不是靠代码审查来回答。请在上线前提出这个问题，因为答案可能会改变你是否需要托管资金。

应选择哪种网络和代币？

对于大多数支付产品，建议选择 Polygon PoS，并使用 USDC 或 USDT 等稳定币。Polygon 文档列出主网的链 ID 为 137，Gas 代币为 POL；Amoy 测试网的链 ID 为 80002。请在签名代码中硬编码链 ID，确保交易永远不会被广播到错误的网络。

团队选择 Polygon 的原因是手续费低，但手续费会随拥堵程度和 POL 价格而变化。应围绕区间设计手续费处理逻辑，并在发送时读取当前的 Gas 价格。使用 Chaingateway 时，GET /api/v2/polygon/gasprice 会返回该价格。

对于看重其流动性和结算能力的客户，以太坊是替代选择。如果两者都需要，使用一个跨链的 API 意味着你只需编写一次付款流程。关于这种组合的另一端，参见 Ethereum API。

即使发送的资产是稳定币，你的发送钱包仍然需要 POL 来支付 Gas。从交易平台向钱包充值时，请选择 Polygon 作为提币网络，并在确认前检查网络标签。提错网络是设置过程中造成资金损失的常见原因。

决策	支付场景的典型选择	原因
网络	Polygon PoS（链 ID 137）	手续费低
付款代币	USDC 或 USDT（ERC-20）	价值稳定，客户熟悉
Gas 代币	POL	每笔交易都需要
通知	Webhook	无需轮询

如何设置钱包并保护密钥？

常见的模式有两种：

每位客户或每张发票一个地址。 每笔付款都有自己的充值地址。这样，把到账转账与订单对应就很简单，因为接收方地址即可标识它。代价是需要管理更多地址，并且之后还要把资金归集到财务钱包。
共用一个地址，附带参考信息。 这种方式运营起来更简单，但普通的代币转账没有参考字段。你最终只能依据金额和时间进行匹配，而当两位客户支付相同金额时，这种匹配就会出错。

对于大多数电商流程，按订单分配地址是更清晰的设计。无论选择哪种方式，都应养成以下习惯：

切勿把私钥保存在源代码管理、日志或客户端代码中。
将接收钱包与持有你余额的财务钱包分开，使其中一个被攻破时不会暴露另一个。
限制可以触发转出的人员和操作，并记录每一次请求。
以能够经受一个人或一台服务器丢失的方式备份密钥材料。

Chaingateway 为非托管服务。POST /api/v2/polygon/addresses 用于创建钱包。如果你发送 password，私钥会用它加密保存，发送交易时你使用密码而不是私钥。Chaingateway 不保存该密码，如果你丢失了密码，也无法恢复钱包。调用流程见使用 API 创建加密货币钱包。

如何在 Polygon 上发送代币付款？

Polygon PoS 兼容 EVM，因此代币转账遵循 ERC-20 标准。ERC-20 规范定义了两种付款模式：

直接付款： 付款方调用 transfer(recipient, amount)，并触发一个 Transfer 事件。
合约代收的拉取付款： 付款方先调用 approve(spender, amount)，然后获得授权的合约调用 transferFrom(sender, recipient, amount)。

对于简单的结账流程，直接转账就足够了。当智能合约代为收款时，例如订阅或托管，授权才变得重要。授权应保持精确：只授权你所需的金额，而不是无限额度。

如何用原始节点代码发送？

直接发送意味着你需要构建交易、估算 Gas、设置 Nonce、签名、广播，并监控其是否被打包。对于原型来说，这是可以应付的。在生产环境中，你还需要可靠的 RPC 服务商、重试逻辑，以及替换卡住交易的方法。我们关于发送 ERC-20 代币的指南比较了钱包、代码和 API 三种方法。

如何用一次 REST 调用发送？

使用 Chaingateway，一笔代币转账只需一次经过身份验证的请求。请求中指明发送方、代币合约、接收方和金额。Gas 字段是可选的。OpenAPI 定义将 from、contractaddress、to 和 amount 标记为必填项。

curl -X POST https://app.chaingateway.io/api/v2/polygon/transactions/erc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0xSenderAddress",
    "contractaddress": "0xTokenContract",
    "to": "0xRecipientAddress",
    "amount": 25.5,
    "password": "wallet-password"
  }'

X-Network: testnet 会在 Amoy 上运行该请求。主网请不要带该请求头。其他 EVM 链也使用相同的模式，因此之后增加第二条链时，改变的是路径，而不是流程。完整的端点列表见 Polygon API 页面和 OpenAPI 文件。

如何验证付款是否到账？

交易哈希只能证明交易已被提交。在将订单标记为已付款之前，请检查交易状态、接收方、代币转账金额和代币合约。ERC-20 转账记录在 Transfer 事件日志中，见 ERC-20 规范的定义，因此应从日志中读取真实的转账信息。

团队最容易忘记的是合约检查。任何人都可以部署一个名为“USDC”、却毫无价值的代币。请将日志中的合约地址与你加入白名单的地址进行比较。你的验证流程应确认以下所有事项：

交易已成功，而不仅仅是被打包。
Transfer 事件来自你预期的代币合约。
接收方与你为该订单签发的地址一致。
金额至少等于你开具的发票金额，并以代币的最小单位计算。
在放行商品之前，已经过了足以满足你风险承受能力的区块数。

直接读取原始日志意味着要手动解码 topic 和 data。我们关于 ERC-20 Transfer 事件的说明展示了其结构。Chaingateway 还可通过 GET /api/v2/polygon/transactions/{txid}/decoded 返回已解码的交易。

如何通过 Webhook 获取通知？

每隔几秒轮询一个地址既浪费请求，而且仍然存在延迟。使用 Webhook 时，服务会在检测到匹配的交易后调用你的端点。使用 POST /api/v2/polygon/webhooks 创建 Webhook。url 字段为必填，并可按 to、from 或 contractaddress 进行过滤。其运作机制见 Polygon Webhook。

如何安全地构建接收端？

以下规则适用于任何服务商：

验证签名。 设置个人密钥后，Chaingateway 会添加 X-Signature 请求头。它是以你的密钥为键，对交易 ID 计算的 Base64 编码 HMAC-SHA256。参见验证 Webhook 签名。
以恒定时间比较。 使用所用语言的安全比较函数，而不是 ==。
快速应答。 立即返回 2xx 状态码，并将繁重的工作放到队列中处理。
预期会有重复。 同一事件可能会收到两次，例如在你重新发送通知之后。应存储交易 ID，并忽略重复项。
预期会有遗漏。 Chaingateway 不会自动重试失败的通知。请使用 GET /api/v2/polygon/webhooks/notifications/failed 列出它们，并通过 POST /api/v2/polygon/webhooks/notifications/{id}/retry 逐条重新发送。

应存储哪些付款状态？

付款状态应保持简短而明确：awaiting_payment、pending、confirmed、failed、expired。每个 Webhook 最多对应一次状态转换。如果某笔已确认付款收到一个失败事件，应记录日志并通知人工处理，而不是覆盖该状态。

后端应如何设计？

将链相关的代码放在边缘。在链前面设置一个内部接口，包含 createDepositAddress、sendPayment 和 getPaymentStatus 等方法，并把订单逻辑放在接口的另一侧。这样，增加一条链就只需实现该接口，而无需重写核心逻辑。

账本应当由你自己掌控。切勿把区块链或服务商控制台当作你的正式账簿。应存储每一笔预期付款、每一笔观察到的转账，以及二者之间的关联，以便在每天结束时进行对账，并解释任何差异。

上线前应检查什么？

请特别测试三件事：失败的交易、Nonce 冲突和 Gas 价格变化。

上线前

在 Amoy 测试网上运行完整流程：创建地址、向其付款、接收 Webhook、将订单标记为已付款。
将每个 Webhook 重放两次，确认第二次投递不会改变任何内容。
发送错误代币的付款、金额错误（不足和超额）的付款，以及付给已过期订单的付款。针对每种情况确定处理方式并进行测试。
故意让你的端点返回 500 错误并超时，然后列出失败的通知并重新发送。
从同一钱包同时发起两笔转账，以暴露 Nonce 冲突。

上线时

从低额度和单一代币开始。
对超过阈值仍处于待处理状态的转账发出警报。
监控 Gas 钱包余额，因为 POL 余额为空会导致所有转出付款停止。
按计划轮换个人密钥，并同时更新接收端。

常见错误

信任哈希，而不是事件日志。
在验证签名之前就信任 Webhook。
硬编码 Gas 价格。
跳过代币合约检查。
把热钱包密钥与财务密钥放在一起。

套餐起价为每月 49 欧元（或每年 490 欧元），提供 7 天免费试用且无需银行卡。见价格页。

常见问题

Polygon 付款应接受哪种代币？

大多数支付产品接受 USDC 或 USDT 等稳定币，因为从开票到付款之间价格不会大幅波动。但任何发送交易的钱包仍需保有少量 POL，因为 Gas 由 POL 支付。应将你接受的代币合约地址精确地加入白名单，并拒绝其他一切。

我需要自己运行 Polygon 节点吗？

不需要。你可以使用托管的 RPC 服务商，或由其代为处理节点访问的区块链 API。只有当你有特定的延迟、隐私或合规需求，并且有团队负责维护时，才值得自己运行节点。

如何避免同一笔付款被入账两次？

为你处理的每笔付款存储唯一的交易 ID，并在更改任何订单状态之前进行检查。具有幂等性的处理程序会把重复事件变成无害的空操作。

支付方面，Polygon 和以太坊哪个更好？

这取决于你看重什么。Polygon PoS 通常每笔交易的成本低于以太坊主网。以太坊拥有更大的用户基础和流动性。许多团队同时支持两者，并让客户自行选择。