跳转到主要内容
本页介绍您可以在商户 Portal → Integration 自行管理的安全设置。请求签名机制见认证与签名 FAQ。

我能在商户 Portal 里自己添加或轮换公钥吗？

可以。生产环境公钥通过 Integration 页面在线提交。每次提交都会注册一条新的密钥记录并配有自己的 API key——不是就地编辑现有密钥。提交会经过 Waffo 审核： 密钥激活或被拒绝时您会收到邮件（拒绝邮件包含原因）。要轮换密钥，请提交新公钥，等待其变为 Active，然后把您的集成切换到新的 API key。确认旧 key 不再有流量后，可以在 Historical Versions 中将其永久撤销，见《生产环境公钥与 API 操作类型》。

为什么提交公钥需要对一个挑战字符串签名？

为了证明您确实持有与所上传公钥配对的私钥。Portal 会显示一个固定的挑战字符串，格式为 WAFFO_VERIFY_{mid}；请用您的私钥在本地对其签名，并把签名与公钥一起提交。Waffo 在接受公钥前会用所提交的公钥验证该签名。 同一个公钥不能为同一商户提交两次。

我可以有多少个 API key 和公钥？

每个 API key 恰好对应一个公钥。一个商户可以持有多个 API key，按 API 操作类型划分范围： 每种操作类型下可持有的公钥数量有上限；这个上限足够宽裕，可以在轮换期间让新旧密钥并行有效，达到上限时 Portal 会提示您。

退款和拒付通知 URL 在哪里配置？

同样在商户 Portal → Integration。与公钥不同，通知 URL 变更无需审核——URL 通过校验后立即生效。校验规则：URL 必须以 http:// 或 https:// 开头，符合 RFC 3986（不含空格或非 ASCII 字符），且不超过 512 个字符。清空字段并保存即删除该配置。生产环境的 Integration 页还可以配置绑卡结果通知 URL（Tokenization Notify URL），其长度上限为 2048 个字符。

我能为不同 API key 设置不同的通知 URL 吗？

不能。每个 MID 有一个全局的 Refund Notify URL 和一个全局的 Chargeback Notify URL——它们不是按 API 操作类型存储的。Chargeback Notify URL 仅适用于卡收单。提现通知不使用这些设置：提现通知 URL 在 API 请求中按订单传入。

怎么把 API 访问限制到我服务器的 IP 地址？

在 Portal 中启用 IP 白名单——这是一项可选的安全措施，默认关闭。启用后，签名有效但来源 IP 不在白名单中的请求会被拒绝并返回错误 A0046（“Access denied: the request IP is not in the whitelist”，HTTP 400）。配置变更在您保存后很快生效——保存同时会使缓存的查询失效，因此实际上通常是立即生效。从未启用它的商户不会看到任何行为变化。 白名单在签名验证之后评估，因此签名错误的请求会以签名错误（A0002）而非 A0046 失败，即便其 IP 也不在名单上。

IP 白名单支持哪些格式和限制？

  • 条目接受 IPv4 地址、IPv6 地址以及两者的 CIDR 网段（例如 203.0.113.7、198.51.100.0/24、2001:db8::1、2001:db8::/64）。IPv4 和 IPv6 条目可以混用，分别匹配；不支持端口、域名、通配符、IP 范围和带 % 的地址。
  • 每个商户最多 20 条；重复条目会被拒绝。
  • 每条可带标签，并可单独启用或停用。
  • 没有任何已启用条目时白名单无法打开，删除或停用最后一条已启用条目会自动关闭总开关。

总开关关闭时添加或停用条目，会发生什么？

总开关关闭时，已有条目都会保留，但不参与校验——API 请求不受 IP 限制。此时在 Portal 添加的新条目会正常保存，Portal 提示它在重新打开 IP 白名单之前不会生效，页面顶部也会显示 “IP whitelist is currently disabled” 的横幅。 反过来，要打开总开关，至少要有一条已启用的条目，否则 Portal 会提示先启用至少一条。关闭总开关、停用某条已启用的条目、删除条目时，Portal 都会弹出确认；如果被停用或删除的是最后一条已启用的条目，确认内容会说明总开关将同时关闭。关闭总开关意味着接受来自任意 IP 的 API 请求，随时可以重新打开恢复保护。 添加条目时，Portal 在保存前会检查格式（只允许数字、字母 a–f、冒号、点和斜杠，单条最长 50 个字符；IPv4 网段前缀为 0–32，IPv6 网段前缀为 0–128）、是否重复，以及是否已达每个商户 20 条的上限。

我填的地址保存后为什么变了样？

Portal 按规范格式保存地址：字母转为小写，连续的 0 组压缩为 ::，网段中的主机位清零；IPv4 映射地址（如 ::ffff:192.0.2.1）保存为对应的 IPv4 地址。输入和保存值不同时，输入框下会提示「将按规范格式保存为 …」。
  • 查重按规范格式比较，写法不同但等价的地址会被判为已在白名单中。
  • 以 ::ffff: 开头的 IPv4 映射网段不接受，请直接填 IPv4 网段。
  • 前缀为 0 的网段（0.0.0.0/0、::/0）会放行该地址族的所有地址。Portal 会提示「该网段会放行所有 IPv4/IPv6 地址」，仍允许保存，但这类条目对该地址族不再有限制作用。
  • 列表的类型列显示 IPv4、IPv4 CIDR、IPv6 或 IPv6 CIDR，地址完整显示并可一键复制。

页面提示「当前仅配置了 IPv4 地址」，我要做什么？

白名单已开启并在拦截、而启用中的条目全部是 IPv4 时，页面会显示这条提醒。如果你的服务器会通过 IPv6 出口访问 Waffo API，请把对应的 IPv6 地址或网段加进来，否则这些请求可能以 A0046 被拦截。确认服务器只走 IPv4 出口时，可以不处理。

如果 Waffo 无法判断我请求的来源 IP 会怎样？

默认情况下，无法判断来源 IP 的请求会被放行并记录日志——只有能够判断且不在白名单中的 IP 才会被拦截。 Waffo 支持比这个默认更严格和更宽松的执行策略，但 Portal 只暴露总开关；策略本身在 Waffo 侧设置。如果您想先以仅观察模式运行，或者需要在无法判断来源 IP 时也拦截请求，请联系集成支持。

登录时的两步验证挑战是怎么工作的？

两步验证是一项登录控制，而不是 Integration 设置——账户侧的问题（谁能开启、验证码一直收不到怎么办）见商户 Portal 操作。机制上它是在登录调用过程中校验的，而不是登录之后：
  1. 您照常提交登录表单。如果账户有已确认的两步验证方式，且距上次成功登录已超过 24 小时，则不会签发会话：登录返回需要挑战的响应，同时验证码已发往账户的登录邮箱。24 小时内再次登录不会触发挑战。
  2. Portal 打开Verification 对话框，附带一个与本次登录尝试绑定的短期重发令牌。
  3. 您输入验证码，Portal 重复同一次登录，这次带上验证码。只有此时才会签发会话。
只对账户的默认方式发起挑战。验证码错误或过期会导致登录本身失败，这就是为什么对话框让您重新输入验证码而不是密码。

为什么登录页开着不动一会儿，Resend 就不管用了？

此时您没有会话，所以 Resend 无法由会话授权。它由挑战时下发的重发令牌授权。该令牌属于单次登录尝试，一段时间后过期；刷新页面或开始新的尝试会丢弃它。如果 Resend 失败，请重新登录——这会签发新的挑战和新的令牌。

两步验证的每个控件实际做什么？

以下都是使用您的 Portal 会话执行的 Portal 操作——它们不属于 API key 签名的商户 API，无法用您的集成密钥编写脚本调用。 三点后果值得了解：
  • **只有验证码被验证后绑定才算生效。**验证码发出后关闭对话框，会让该尝试停留在未确认状态，两步验证保持关闭；再次打开开关会开始新一轮。
  • 您首个确认的方式成为默认——而默认方式就是登录挑战使用的方式。
  • 关闭由您的密码授权，而不是验证码，密码以与登录表单密码相同的方式加密传输。密码错误会返回标准的密码错误，该方式保持绑定。