payment-provider-framework

用途

本技能适用于在 VTEX IO 上开发或维护支付连接器（Payment Connector），即以 VTEX IO 应用形式实现、而非自行托管的独立 HTTP 服务。需要在 node/index.ts 中接入 @vtex/payment-provider、PaymentProvider 与 PaymentProviderService，配置 paymentProvider builder 与 configuration.json，实现网关重试语义，并在卡流程中使用 Secure Proxy。

以下情况不在本技能范围内：PPP HTTP 契约与九个端点逐字段要求（使用 payment-provider-protocol）；幂等与重复 paymentId 处理（使用 payment-idempotency）；异步 undefined 状态、callbackUrl 通知与 retry 的区别（使用 payment-async-flow）；PCI 规则、日志与令牌语义（使用 payment-pci-security）；POS / Sales App 的卡在场叠加（使用 payment-ppp-pos 并结合本技能）。

主要能力与决策规则

PPF on IO 是 VTEX IO 上构建支付连接器的方式，应用使用 IO 基础设施，API 路由、请求/响应类型与 Secure Proxy 按 VTEX 指南集成，建议从官方文档描述的示例应用起步。

前置条件：遵循 Payment Provider Protocol 文章与「Integrating a new payment provider on VTEX」指南中的实现前置要求。

依赖：在应用的 node 目录添加 @vtex/payment-provider（例如 package.json 中 1.x）；将 @vtex/api 保留在 devDependencies（例如 6.x），链接时可能将其提升到 6.x 以上，这可以接受。若类型出错，删除项目根目录与 node 中的 node_modules 与 yarn.lock，分别在两处运行 yarn install -f。

paymentProvider builder：在 manifest.json 中于 node 旁加入 "paymentProvider": "1.x"，以便应用支付网关回调与 PPP 路由的策略。

configuration.json：声明 paymentMethods，使 builder 能够实现它们而无需在 /manifest 上重复声明；名称需匹配 List Payment Provider Manifest API 参考，只有确实是新方法时才自创名称。Admin 中的新方法可能需要支持工单。

PaymentProvider：每个 PPP 路由对应一个类方法；TypeScript 会强制类型形状。

PaymentProviderService：注册默认路由 /manifest、/payments、/settlements、/refunds、/cancellations、/inbound；需要时传入额外路由 / clients。

覆盖 /manifest：仅在用例获批时进行，需开工单。

可配置选项：通过 configuration.json / builder 选项设置 implementsOAuth、implementsSplit、usesProviderHeadersName、usesBankInvoiceEnglishName、usesSecureProxy、requiresDocument、acceptSplitPartialRefund、usesAutoSettleOptions 等开关。设置 name，并在 IO 上依赖自动生成的 serviceUrl，除非文档另有说明。不要自创字段——未知键（如 usesTestSuite）会导致 builder 校验错误。

网关重试：在 PPF 中，当协议要求重试时调用 this.retry(request)。

IO 上的卡数据：优先使用 SecureExternalClient，并传入来自 Create Payment 的 secureProxyUrl，目标必须被加入允许列表。Secure Proxy 支持的 Content-Type 仅为 application/json 与 application/x-www-form-urlencoded。重要：只有 Create Payment（授权）请求携带 secureProxyUrl；授权后的操作（取消、捕获、退款）不传输卡数据，必须通过 ExternalClient 携带凭据与出站访问策略直接调用 PSP API。

结账测试：账户须被允许使用 IO 连接器（提交含应用名与账户的工单）。发布 beta，在 master 安装，等待约 1 小时，打开 affiliation URL，启用测试模式与工作区，配置支付条件（约 10 分钟），下测试订单；之后进行 stable 与 homologation。

发布：按 Billing Options 指南配置 billingOptions，并通过「Submitting your app」提交。按指南准备 homologation 材料（连接器应用名、合作伙伴联系方式、生产端点、允许的账户、新方法/流程），SLA 通常约 30 天。

更新：在 new beta 中发布变更，重新测试 affiliations，然后 stable；如需则重新 homologate。

硬性约束

Builder-Hub 使用 TypeScript 3.9.7，代码与依赖必须兼容。builder-hub 还用 TS 3.9.7 编译 IO 应用，并忽略 tsconfig.json 中的 skipLibCheck: true——node_modules 中每个 .d.ts 文件都会被类型检查，因此即便自身代码有效，某个传递依赖携带现代 .d.ts 语法也会导致构建出现大量无关错误。

禁止的语法（与 TS 3.9.7 不兼容）：模板字面量类型（4.1）；类型化 catch 子句（4.0）；override 关键字（4.3）；import type ... = require()（4.5）；satisfies 运算符（4.9）。

正确的 catch 写法：

try {
  // ...
} catch (error) {
  const err = error as any
  console.log(err.message)
}

错误写法：

try {
  // ...
} catch (error: any) {
  console.log(error.message)
}

未使用变量是错误而非警告：builder-hub 将声明但未使用的变量视为编译错误，避免解构未用字段。

安全依赖版本（与 TS 3.9.7 兼容）：在 node/package.json 中使用 resolutions 将传递依赖固定到不携带现代 .d.ts 语法的版本，**/<package> 模式可固定嵌套副本。示例：@types/node 12.20.55；@types/express-serve-static-core 4.17.2；@types/express 4.17.10；@types/koa 2.15.0；@opentelemetry/api 1.0.4；@types/serve-static 1.15.0；typescript 3.9.7。首个破坏版本：@types/node 13.x+（部分 API）；@types/express-serve-static-core 4.17.13+（模板字面量类型）；@types/express 4.17.11+（依赖 @types/express-serve-static-core@^4.17.18）；@types/koa 3.x（import type ... = require()）；@opentelemetry/api 更新版本（TS 4.x 语法）；@types/serve-static 更新版本（传递依赖问题）。若构建在 node_modules 的 .d.ts 中报错，可从错误路径定位包，测试更早版本直到无现代语法，并同时加入 devDependencies 与 resolutions（带 **/<package> 模式）。

configuration.json 必须只使用有效 schema 字段与正确的 customFields 格式：paymentProvider builder 会按严格 schema 校验 configuration.json，未知字段会导致构建错误；select 类型字段的 customFields[].options 数组必须使用 text 与 value 键，绝不能用 label。规范字段（请对照当前 VTEX 文档核实）：name（必填）、serviceUrl（IO 上自动）、implementsOAuth、implementsSplit、usesProviderHeadersName、usesBankInvoiceEnglishName、usesSecureProxy、requiresDocument、acceptSplitPartialRefund、usesAutoSettleOptions、paymentMethods、customFields。已知会破坏构建的字段：usesTestSuite。

manifest.json 必须声明 paymentProvider builder，configuration.json 中须有真实连接器身份与非占位符 name 和准确的 paymentMethods，不得将字面占位符 "MyConnector" 作为生产配置。

仅通过 PaymentProviderService 与 PaymentProvider 实现注册 PPP 路由。

PaymentProviderService 的 clients 字段需要 { implementation, options } 而非直接传类：

import { PaymentProviderService } from '@vtex/payment-provider'
import MyConnector from './connector'
import { Clients } from './clients'

export default new PaymentProviderService({
  connector: MyConnector,
  clients: {
    implementation: Clients,
    options: {
      default: {
        retries: 2,
        timeout: 15000,
      },
    },
  },
})

在 IO 上使用 this.retry(request) 进行网关重试，而非自定义重试逻辑。

在 IO 上通过 Secure Proxy 转发卡授权调用，目标须在允许列表中，并通过 SecureExternalClient 传入 secureProxyUrl，仅支持 application/json 或 application/x-www-form-urlencoded 请求体。若 usesSecureProxy 为 false，提供方必须 PCI 认证并提供 serviceUrl 的 AOC。

只有 Create Payment 请求携带 secureProxyUrl；取消、捕获、退款等授权后操作不带卡数据，必须使用来自 @vtex/api 的 ExternalClient 携带 API 凭据直接调用 PSP API，并在 manifest.json 中由 outbound-access 策略保护。

适用场景

在 VTEX IO 上创建或维护支付连接器、接入 PPP 路由与网关策略、配置支付方式与自定义字段、处理卡数据安全代理、进行支付关联测试与发布/homologation 流程。

限制

本技能不覆盖 PPP HTTP 契约逐字段要求、幂等处理、异步流程、PCI 规则细节与 POS 卡在场场景，这些需使用对应的其他技能。所有依赖版本、schema 字段与流程以当前 VTEX 官方文档为准；部分流程（如 Admin 新支付方法、/manifest 覆盖）需要支持工单。

技能介绍

用途

主要能力与决策规则

硬性约束

适用场景

限制