支付 API 密钥的作用类似于一张没有 PIN 码的现金卡。持有者只要发送该密钥，就能创建发票、读取您的支付数据，并且如果您使用了付款功能，还能将资金从您的余额中转出。因此，支付 API 安全归结为三个习惯：将密钥保存在您自己的服务器上，只允许这些服务器的地址调用 API，并在采取行动前通过回读支付信息来确认每一个 Webhook。
本指南面向支付服务提供商（PSP）、电子货币机构（EMI）、银行以及商户中负责工程的负责人和支付负责人，这些机构正在对接以欧元结算的加密支付 API。本文将说明如何通过 IP 地址和无类别域间路由（CIDR）范围限制密钥、密钥应存放的位置、如何核验 Webhook，以及付款功能周边应配备哪些控制措施。示例使用 ItisPay API 和控制台（演示数据）。
关键时刻
要点速览
- API 密钥是一种持有者凭证。GitGuardian 统计显示，2025 年公开的 GitHub 提交中新增了 2865万个硬编码密钥，因此规划时应假设密钥会泄露，而不只是设法保管好它。
- IP 白名单可使泄露的密钥在您的网络之外失效。请列出能覆盖您实际出站地址的最小 IPv4 或 IPv6 范围；空列表则允许所有地址。
- Webhook 只是通知，并非凭证。在发货或为账户入账之前，请使用您的密钥通过发票 ID 重新读取该发票。
- 付款操作需要您这一侧的人工控制：两步登录、已保存的收款方 IBAN 和钱包，以及超过设定金额时的第二审批人。
为什么支付 API 密钥泄露如此危险？#
支付 API 密钥泄露之所以危险，是因为该密钥即代表您整个集成的身份。与大多数支付 API 一样，ItisPay API 使用一个请求头 Api-key 对每个请求进行身份验证，同一套认证同时覆盖发票、向 IBAN 或钱包的付款，以及向外部地址的加密货币提现。这正是文档要求密钥“不得暴露在客户端代码或公共代码仓库中”的原因。
实践中，密钥通常通过日常场所泄露：代码、日志和聊天记录。据 GitGuardian《2026 年密钥扩散状况》（2026 年 3 月）称，2025 年公开的 GitHub 提交中新增了 2865 万个硬编码密钥，比上一年多 34%。GitGuardian 在 2026 年 1 月重新测试 2022 年泄露的密钥时，仍有超过 64% 有效。团队会公开密钥，之后却忘记更换。
OWASP API Security Top 10（2023 年）将“Broken Authentication（失效的身份认证）”列为第二大风险，并警告称：“认证机制是攻击者的易攻目标，因为它对所有人都是可见的。”Verizon《2025 年数据泄露调查报告》认为，凭证滥用是最常见的初始攻击途径，占比 22%。仅靠一串密钥字符串的防御十分薄弱，因此本指南其余部分将增加一些即使字符串已外泄仍然有效的防护层。
IP 白名单如何保护 API 密钥？#
IP 白名单（也称 IP 允许列表）通过将密钥与地点而不仅仅是字符串绑定来保护密钥。只有当请求来自您列出的地址时，API 才会接受该密钥；开发人员笔记本电脑、CI 日志或粘贴网站上的密钥副本都无法使用。
在 ItisPay 控制台中，该设置位于“项目”→“设置”→“安全”下的“API 允许的 IP”字段。该字段接受以逗号分隔的单个地址和 CIDR 块列表。其帮助文字写道：“留空则允许所有 IP。同时支持 IPv4 和 IPv6。”创建项目时也可通过 API 的 api_allowed_ips 字段设置同一列表；无效条目（例如 256.256.256.256）会被拒绝并返回验证错误，而不会被保存。
默认留空很关键。新项目在有人填写该字段之前，会允许任何地方使用其密钥，因此应将此步骤列入上线清单，而不是以后再整理的事项。截图中的演示值 203.0.113.10 和 198.51.100.0/24 来自 RFC 5737 为文档保留的地址段；您的列表应填入您自己的公网地址。每个项目都有自己的 64 个字符的密钥和自己的列表，因此生产环境可以只锁定在两三台服务器上，而测试项目则可接受更宽的范围。
如何为 IPv4 和 IPv6 编写 CIDR 范围？#
编写能覆盖您服务器实际用于访问 API 的每个地址的最小范围。大多数白名单问题源于范围过宽，或者遗漏了某条出站路径。
理解前缀#
CIDR 块由一个地址、一个斜杠和一个前缀长度组成。RFC 4632 将前缀长度定义为有效位数：192.168.99.0/24 固定了前 24 位，剩下 8 位可变，因此共有 256 个地址。前缀每减少一位，块的大小就翻一倍。/32 为一个 IPv4 地址，/29 为 8 个，/24 为 256 个，/16 为 65,536 个。
IPv6 的原理相同，只是有 128 位。/128 为一个地址。RFC 4291 将大多数 IPv6 地址的接口部分设为 64 位，因此服务器所在网络通常为 /64，主机可以在其中更改地址，例如操作系统生成临时地址时。如果您主机的 IPv6 地址会变化，而该 /64 仅归您所有，请列出该 /64 而不是单个 /128。IPv6 示例所用的文档地址段为 2001:db8::/32（RFC 3849），因此切勿将其复制到真实的白名单中。
查找您真实的出站地址#
重要的是 API 所看到的地址，而不是您的服务器自报的地址。在云 NAT 网关或企业防火墙之后，许多机器共用一两个公网地址。无服务器函数通常从共享地址池出站，除非您将其路由至固定的出口。请在每个环境中调用“我的 IP 是什么”之类的服务进行检查，或从防火墙日志中读取源地址，然后精确列出该地址。
| 设置 | 应列入的内容 | 结论 |
|---|---|---|
| 一台具有静态公网 IPv4 地址的服务器 | 该地址，写作 /32 或直接填写 | 可行 |
| 位于云 NAT 网关之后的多台服务器 | NAT 网关的公网地址 | 可行 |
| 地址会变化的 IPv6 主机 | 该主机的 /64，前提是没有其他人使用它 | 视情况而定 |
| 用于手动测试的办公室网络 | 办公室的固定地址，前提是服务商保证其固定 | 视情况而定 |
| 无固定出口的无服务器函数 | 先通过带静态地址的 NAT 路由它们 | 不可行 |
| 云服务商的整个区域地址段 | 无需列入；该地址段也覆盖其他客户 | 不可行 |
保存更改前，请先添加新地址，部署，确认流量正常通过，然后再删除旧地址。若列表中遗漏了您正在使用的服务器，将阻断您自己的结账。
API 密钥应存放在何处，谁能看到它？#
密钥应仅存放在您的服务器上的密钥存储中，不得存放于其他任何地方。切勿将其打包进浏览器页面或移动应用，因为任何人都可以在那里读取它。也不要将其放入 URL：OWASP REST 安全速查表警告称，URL 中的密钥可能被 Web 服务器日志捕获。您的结账页面与后端通信；后端再与支付 API 通信。
在启动时从密钥管理器或环境变量加载密钥，而不是从代码仓库中的配置文件加载。如果您将代码托管在 GitHub 上，请开启推送保护。根据 GitHub 文档，当它“在推送尝试期间检测到潜在机密时，将阻止该推送。”
每个环境使用一个密钥。每个 ItisPay 项目都有自己的密钥和允许列表，因此为生产环境和预发布环境分别设置项目，意味着泄露的预发布密钥无法影响实时支付。严格限制可以查看生产密钥的人员。欧洲银行管理局（EBA）2019 年关于 ICT 安全的指南确立了“按需知悉”访问原则，并规定“最低访问权限”，技术用户同样适用；自 2025 年起，欧盟《数字运营韧性法案》（DORA）将这一义务延伸至大多数支付机构。
然后，在您真正需要之前，就写下如何更换密钥的方案。OWASP 加密存储速查表建议在设定周期后以及怀疑密钥泄露时轮换密钥，并确保“在需要之前，轮换密钥所需的代码和流程已经就位。”
如何验证支付 API 的 webhook？#
请将 webhook 视为“某事已发生变化”的通知，切勿将其视为您已收款的证明。任何获知您回调 URL 的人都可以向其发送伪造的“已完成”消息。安全的做法是使用您自己的密钥从 API 回读发票，并根据 API 返回的内容采取行动。
创建 ItisPay 发票时，callback_url 字段用于设置状态更新的地址。收到 webhook 时，从中获取发票 ID，按 ID 对该发票调用 GET，并且仅当该响应显示您预期的状态和您定价的金额时，才发货或入账。文档将该端点描述为返回支付状态和区块链详情，“供向用户展示或用于验证”。
以下规则可使处理程序保持简洁：
- 仅通过 HTTPS 接收 webhook，拒绝明文 HTTP。
- 使处理程序具备幂等性。存储每个已处理的发票 ID 及状态，并跳过重复项，因为服务商会重新发送通知。
- 快速响应，并将实际工作放入队列中处理，以免数据库缓慢而触发重试。
- 如果服务商使用 HMAC 为 webhook 签名（HMAC 是 RFC 2104 定义的一种带密钥哈希），请重新计算签名，并使用恒定时间函数进行比较。OWASP Webhook 安全速查表言辞直接：“切勿使用 ==：它会泄露计时信息，并可能使该端点变成签名预言机。”拒绝签名时间戳过旧的消息。
上线前进行测试。ItisPay 提供一个端点，可为真实的测试发票模拟状态变更；另一个端点可针对某个发票或订单 ID 重新发送最新的 webhook，使您无需真实资金即可检查重试和重复情况。
如何锁定付款和控制台访问权限？#
一旦密钥被盗，就会转化为资金损失，因此需要在付款环节增加人工控制。通过 ItisPay 付款端点，法币付款会发送至收款人 IBAN，加密货币付款则发送至钱包地址，两者均从您的可用余额中扣除。API 会按请求执行操作；判断请求是否合法是您的责任。
您一方可采取的有效控制措施：
- 对所有拥有控制台或付款权限的人员实施两步登录。欧盟支付法规对支付用户已采用这一理念：PSD2 关于强客户认证的规则要求至少两个独立要素，分别来自知识、持有物和固有特征。对您自己的员工同样应适用这一标准。
- 已保存的收款人。维护您自己批准的 IBAN 和钱包地址清单，并且仅允许您的付款服务向清单中的条目付款。新收款人需经过单独审批，最好设置冷静期。
- 超过阈值时需第二名审批人。一人准备，另一人审批。金额阈值应根据您自身的风险偏好设定。
- 独立的付款服务。从一个拥有自身固定地址并列入允许列表的服务运行付款，并与负责创建发票的结账服务器分开。
| 控制措施 | 可阻止的情况 | 结论 |
|---|---|---|
| 密钥的 IP 白名单 | 在您的网络之外使用泄露的密钥 | 有效 |
| 密钥仅存放在服务器上 | 从浏览器、应用和代码仓库中窃取密钥 | 有效 |
| 收到 webhook 后重新读取发票 | 伪造的“已支付”通知 | 有效 |
| 已保存的收款人与第二审批人 | 付款至攻击者的 IBAN 或钱包 | 有效 |
| 仅靠其中任何一项，无法防范白名单内被入侵的服务器 | 已在内部的人实施的盗窃 | 无效 |
DORA 和 PCI DSS 对 API 访问有哪些要求？#
如果您是受监管的欧盟金融机构，这些控制措施并非可选的附加项。《数字运营韧性法案》（Digital Operational Resilience Act，DORA，Regulation (EU) 2022/2554）自 2025年1月17日起适用，这一点据欧洲银行管理局（EBA）介绍。其第 9 条要求机构“实施限制对 ICT 资产的物理或逻辑访问的政策”，并“实施强身份验证机制的政策和协议”。一把仅限白名单、仅存于服务器端并附有轮换计划的密钥，正是审计人员会要求查看的证据类型。
支付卡行业数据安全标准（PCI DSS）涵盖的是卡数据，而非加密货币发票。如果同一团队也运营卡支付，要求 8.4.2 规定须对进入持卡人数据环境的所有访问启用多因素身份验证；而 4.0 版中的未来生效要求已于 2025年3月31日起强制执行。
支付 API 安全控制在哪些环节会失效？#
这些控制措施只是收窄了进入的途径，本身并不能保证集成的安全。即便对于 webhook 发送方而言，OWASP webhook 指南也将 IP 白名单称为“仅是额外一层”，因为“共享的出口 IP 并不能证明身份”。
不起作用的情况
- 白名单内的服务器被入侵。攻击者从受信任的地址、凭借真实密钥发送请求。
- 共享的出口地址。若其他租户通过同一 NAT 地址出云，白名单便无法将他们与您区分开。
- 在未启用两步登录的情况下，控制台密码被盗。攻击者根本无需使用 API。
- 发票字段中的个人数据。ItisPay 的公开发票端点无需密钥即可返回未结发票的全部详情，因此请勿将客户姓名和邮箱放入订单名称中。
如何在一个下午完成安全集成的搭建？#
如果按照固定顺序操作，您便可在一个下午完成安全集成的技术部分。以下步骤以 ItisPay 为例；同样的顺序适用于任何服务商。
- 创建一个测试项目和一个独立的生产项目，每个项目各自拥有独立的密钥。
- 将两把密钥都存入您的密钥管理器，并且仅在服务器端加载。
- 找到每个环境的公网出口地址，并将其填入 API Allowed IPs。
- 从后端创建发票：向 https://api.itispay.com/api/v1/invoices 发送 POST 请求，附带 Api-key 请求头、唯一的 order_id、fiat_amount 及 fiat_currency EUR、currency 中的币种，以及您的 callback_url。
- 构建 webhook 处理程序：仅使用 HTTPS、保证幂等，并在执行任何操作前通过 ID 重新读取发票。
- 为您处理的每个状态运行 webhook 模拟，然后使用重发端点测试重复通知。
- 最后开启付款功能，并启用已保存的收款人和第二审批人。
如需快速上手，控制台中的 Ask AI 助手可应要求编写示例代码，例如在已包含 Api-key 请求头的情况下，用 Node.js 编写的发票调用代码。请将其视为草稿：上线前请对照 API 参考文档核对字段名称，因为参考文档而非生成的示例才是准绳。ItisPay 还在 npm 上发布了官方 TypeScript 客户端 @itispay/typescript-client。
如果您要将此方案接入更广泛的支付编排体系，请为每个服务商分别配置独立的密钥、白名单和 webhook 处理程序。同样的“按 ID 重新读取”记录也可为您的财务团队提供加密支付对账所需的数据。
如果您希望接受稳定币支付并收取欧元，而无需自行搭建整套系统，ItisPay 可提供 API、发票、webhook 和对账服务，以及支付 API 安全的第一层防护：您可将密钥限制为自己的 IP 地址。牌照申领、KYC 以及结算至您的 IBAN 均通过我们与欧盟获许可的加密资产服务提供商（CASP）+ 支付机构合作伙伴完成，多数团队从 KYB 到首笔交易不足一周即可完成。
本文仅供参考，不构成法律或监管建议。
