BTCPay 2.4.4后：核旧API、Key ID与权限迁移
链小知 · 进阶 · 核验 · 依官方文档整理
检查已有集成是否仍依赖被移除的旧密钥或通知字段，不重新申请或操作账户。
开始前准备
- 准备已有且脱敏的订单、请求或回执记录；没有实际记录时仅按文档列出待核字段。
- 本教程依据公开资料，不登录、申请密钥、调用业务API、创建收款或执行退款。
1. 固定实例版本和集成方式
从已有实例信息确认是否为2.4.4或之后，再对照集成的API类型。2.4.4官方release移除旧BitPay Basic-auth API keys；这属于BTCPay兼容接口变更，不表示BitPay商户产品停用。
已有Greenfield集成与旧BitPay式集成分别记录。WHMCS在2.4.4需插件v4.0.0及新Greenfield配置；本文只列缺口，不安装或更换密钥。
检查结果：实例版本、接口类型和插件版本有证据；未知不算已迁移。
2. 区分认证secret与撤销ID
当前Greenfield schema的ApiKeyData区分id与apiKey：认证头使用Authorization: token {token}；撤销路径/api/v1/api-keys/{apiKeyId}使用id，2.4.4不再用secret作撤销标识。
created为Unix时间，旧于2.4.4的密钥可为null；缺创建时间不表示新生成。只核脱敏字段名，任何实际secret不写入审计表；本文不执行DELETE或生成密钥。
检查结果：认证字段与apiKeyId分列，旧created为空保留原含义。
3. 核读取和修改状态的权限
API Key只能限制所属用户已有权限，不能扩大用户角色。权限可按storeId限定；读取发票对应btcpay.store.canviewinvoices，修改发票状态对应btcpay.store.canmanageinvoicestatus。
2.4.4修正修改状态所需权限，并阻止受限key创建unrestricted key。不要因读取成功就推断拥有改状态权限，也不为排错申请unrestricted权限。
检查结果：用户角色、store作用域及读/改权限分别有证据。
4. 检查回调入口而非猜付款丢失
2.4.4 Point of Sale移除每请求notificationUrl，发票使用app配置的通知URL。已有POS请求仍传此字段时，核app配置和回调记录，不能沿用旧参数判断新通知地址。
此变更是POS通知入口，不是所有Greenfield Webhook停用。回调缺失与发票链上付款状态分别核对；无法取得实际配置时交实例维护者继续确认。
检查结果：旧请求字段、app通知配置与发票状态分别记录。
怎样确认完成
- 形成订单、资源ID、金额、状态与未验证项的对照；保留失败原文。
常见错误与边界
- 发布文档中的Lightning外部访问恢复是当时计划，本文不提供开启路由步骤。
- 不调用身份/业务接口，不撤销密钥、不修改发票状态，也不以版本号证明部署安全。