payment-provider-framework

Apply when designing or implementing a Payment Connector in VTEX IO. Covers PPF implementation, TypeScript 3.9.7 builder-hub constraints and safe dependency resolutions, configuration.json schema validation, PaymentProviderService clients wiring, Secure Proxy scope (authorize-only), ExternalClient vs SecureExternalClient patterns, IOContext access, PPF response helpers, PSP integration checklist, and vtex link debugging. Use for any implementation of a Payment Connector hosted in VTEX IO.

Zur Installation springen

Repository: vtex/skills
Letzte Quellaktivität: 29. April 2026 um 21:19
Erkannte Sprache von SKILL.md: Englisch
Sterne: 39
Forks: 9

Installationsoptionen

Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.

Quelldateien prüfen

Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.

Zurück zur Suche Zurück zur Installation

callbackUrl

PPF on IO: "Payment Provider Framework is the VTEX IO–based way to build payment connectors." The app uses IO infrastructure; API routes, request/response types, and Secure Proxy are integrated per VTEX guides. Start from the example app described in the official Payment Provider Framework documentation.
Prerequisites: Follow implementation prerequisites in the Payment Provider Protocol article and the guide on integrating a new payment provider on VTEX.
Dependencies: In the app node folder, add @vtex/payment-provider (for example 1.x in package.json). Keep @vtex/api in devDependencies (for example 6.x); linking may bump it beyond 6.x, which is acceptable. If types break, delete node_modules and yarn.lock in the project root and in node, then run yarn install -f in both.
paymentProvider builder: In manifest.json, include "paymentProvider": "1.x" next to node so policies for Payment Gateway callbacks and PPP routes apply.
configuration.json: Declare paymentMethods so the builder can implement them without re-declaring everything on /manifest. Use names matching the List Payment Provider Manifest API reference; only invent a new name when the method is genuinely new. New methods in Admin may require a support ticket.
PaymentProvider: One class method per PPP route; TypeScript enforces shapes — see Payment Flow endpoints in the API reference.
PaymentProviderService: Registers default routes /manifest, /payments, /settlements, /refunds, /cancellations, /inbound; pass extra routes / clients when needed.
Overriding /manifest: Only with an approved use case — open a ticket. See the Preferred pattern section for an example route override shape.
Configurable options: Use configuration.json / builder options for flags such as implementsOAuth, implementsSplit, usesProviderHeadersName, usesBankInvoiceEnglishName, usesSecureProxy, requiresDocument, acceptSplitPartialRefund, usesAutoSettleOptions. Set name and rely on auto-generated serviceUrl on IO unless documented otherwise. Do not invent fields — unknown keys (such as usesTestSuite) cause builder validation errors. See the "configuration.json schema" constraint below for the canonical list and customFields format.
Gateway retry: In PPF, call this.retry(request) where the protocol requires retry — see the Payment authorization section in the PPP article.
Card data on IO: "Prefer SecureExternalClient with secureProxy: secureProxyUrl from Create Payment; destination must be allowlisted." Supported Content-Type values for Secure Proxy: application/json and application/x-www-form-urlencoded only. Important: only the Create Payment (authorize) request carries secureProxyUrl. Post-authorization operations (cancel, capture, refund) do not transport card data and must call the PSP API directly via ExternalClient with credentials and outbound-access policies.
Checkout testing: Account must be allowed for IO connectors (ticket with app name and account). Publish beta, install on master, wait ~1 hour, open affiliation URL, enable test mode and workspace, configure payment condition (~10 minutes), place test order; then stable + homologation.
Publication: Configure billingOptions per the Billing Options guide; submit via Submitting your app. Prepare homologation artifacts (connector app name, partner contact, production endpoint, allowed accounts, new methods/flows) per the Integrating a new payment provider on VTEX guide (SLA often ~30 days).
Updates: Ship changes in a new beta, re-test affiliations, then stable; re-homologate if required.

Syntax	Minimum TS version	Example
Template literal types	4.1	type X = `${string}/${string}`
Typed catch clause	4.0	`catch (error: any)`
`override` keyword	4.3	`override method()` in classes
`import type ... = require()`	4.5	`import type X = require("pkg")`
`satisfies` operator	4.9	`obj satisfies Type`

// CORRECT — TS 3.9.7 compatible
try {
  // ...
} catch (error) {
  const err = error as any
  console.log(err.message)
}

// WRONG — TS 4.0+ only
try {
  // ...
} catch (error: any) {
  console.log(error.message)
}

// WRONG — if callbackUrl is not used, build fails
const { paymentId, callbackUrl, value } = authorization

// CORRECT
const { paymentId, value } = authorization

{
  "dependencies": {
    "@vtex/payment-provider": "1.x"
  },
  "devDependencies": {
    "@vtex/api": "6.50.1",
    "@types/node": "12.20.55",
    "@types/express-serve-static-core": "4.17.2",
    "@types/express": "4.17.10",
    "@types/serve-static": "1.15.0",
    "@opentelemetry/api": "1.0.4",
    "typescript": "3.9.7"
  },
  "resolutions": {
    "@types/node": "12.20.55",
    "@types/express-serve-static-core": "4.17.2",
    "@types/express": "4.17.10",
    "@types/serve-static": "1.15.0",
    "@opentelemetry/api": "1.0.4",
    "**/@types/express-serve-static-core": "4.17.2",
    "**/@types/koa": "2.15.0"
  }
}

Package	Safe version	First broken version	Reason
`@types/node`	`12.20.55`	`13.x+` (some APIs)	Modern syntax in `.d.ts`
`@types/express-serve-static-core`	`4.17.2`	`4.17.13+`	Template literal types
`@types/express`	`4.17.10`	`4.17.11+`	Depends on `@types/express-serve-static-core@^4.17.18`
`@types/koa`	`2.15.0`	`3.x`	`import type ... = require()`
`@opentelemetry/api`	`1.0.4`	Newer versions	TS 4.x syntax
`@types/serve-static`	`1.15.0`	Newer versions	Transitive dependency issues

{
  "name": "AcmePayConnector",
  "usesAutoSettleOptions": true,
  "paymentMethods": [
    { "name": "Visa", "allowsSplit": "onCapture" }
  ],
  "customFields": [
    {
      "name": "Environment",
      "type": "select",
      "options": [
        { "text": "Sandbox", "value": "sandbox" },
        { "text": "Production", "value": "production" }
      ]
    }
  ]
}

{
  "customFields": [
    {
      "name": "Environment",
      "type": "select",
      "options": [
        { "label": "Sandbox", "value": "sandbox" }
      ]
    }
  ]
}

{
  "name": "PartnerAcmeCard",
  "paymentMethods": [
    { "name": "Visa", "allowsSplit": "onCapture" },
    { "name": "BankInvoice", "allowsSplit": "onAuthorize" }
  ]
}

{
  "name": "MyConnector",
  "paymentMethods": []
}

import { PaymentProviderService } from "@vtex/payment-provider";
import { YourPaymentConnector } from "./connector";

export default new PaymentProviderService({
  connector: YourPaymentConnector,
});

// Ad-hoc router only — no PaymentProviderService / PaymentProvider base
export default someCustomRouterWithoutPPPPackage;

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,
      },
    },
  },
})

export default new PaymentProviderService({
  connector: MyConnector,
  clients: Clients,  // WRONG — expects { implementation, options }
})

// Inside a PaymentProvider subclass method, when the protocol requires retry:
return this.retry(request);

// Re-implementing gateway retry with setTimeout/fetch instead of this.retry
await fetch(callbackUrl, { method: "POST", body: JSON.stringify(payload) });

import { SecureExternalClient, CardAuthorization } from "@vtex/payment-provider";
import type { InstanceOptions, IOContext, RequestConfig } from "@vtex/api";

export class MyPCICertifiedClient extends SecureExternalClient {
  constructor(protected context: IOContext, options?: InstanceOptions) {
    super("https://pci-certified.example.com", context, options);
  }

  public authorize = (cardRequest: CardAuthorization) =>
    this.http.post(
      "authorize",
      {
        holder: cardRequest.holderToken,
        number: cardRequest.numberToken,
        expiration: cardRequest.expiration,
        csc: cardRequest.cscToken,
      },
      {
        headers: { Authorization: "Bearer ..." },
        secureProxy: cardRequest.secureProxyUrl,
      } as RequestConfig
    );
}

// Direct outbound call with raw card fields and no secureProxy
await http.post("https://acquirer.example/pay", { pan, cvv, expiry });

// clients/pspSecure.ts — for authorization only (via Secure Proxy)
import { SecureExternalClient } from "@vtex/payment-provider";
import type { InstanceOptions, IOContext } from "@vtex/api";

export class PspSecureClient extends SecureExternalClient {
  constructor(ctx: IOContext, opts?: InstanceOptions) {
    super("https://api.psp.com", ctx, opts);
  }

  public async authorize(data: object, secureProxyUrl: string) {
    return this.http.post("/v1/payments", data, {
      secureProxy: secureProxyUrl,
    } as any)
  }
}

// clients/psp.ts — for cancel, capture, refund (direct calls)
import { ExternalClient } from "@vtex/api";
import type { InstanceOptions, IOContext } from "@vtex/api";

export class PspClient extends ExternalClient {
  constructor(ctx: IOContext, opts?: InstanceOptions) {
    super("https://api.psp.com", ctx, opts);
  }

  public async capture(transactionId: string, amount: number) {
    return this.http.post(`/v1/payments/${transactionId}/capture`, { amount })
  }

  public async cancel(transactionId: string) {
    return this.http.post(`/v1/payments/${transactionId}/cancel`, {})
  }

  public async refund(transactionId: string, amount: number) {
    return this.http.post(`/v1/payments/${transactionId}/refund`, { amount })
  }
}

// WRONG — trying to use SecureExternalClient for capture
async settle(settlement: SettlementRequest) {
  const client = this.context.clients.pspSecure as PspSecureClient
  // secureProxyUrl is undefined here — this will fail
  await client.capture(settlement.tid, settlement.value, settlement.secureProxyUrl)
}

// Inside the client class — this.http is accessible (protected = same class)
export class PspClient extends ExternalClient {
  public async capturePayment(tid: string, amount: number) {
    return this.http.post(`/v1/payments/${tid}/capture`, { amount })
  }
}

// Inside the connector — call the public method
async settle(settlement: SettlementRequest) {
  const clients = this.context.clients as any as { psp: PspClient }
  return clients.psp.capturePayment(settlement.tid, settlement.value)
}

// Inside the connector — .http is protected, build fails
async settle(settlement: SettlementRequest) {
  const clients = this.context.clients as any as { psp: PspClient }
  return clients.psp.http.post(`/v1/capture`, { amount: settlement.value })
  //                  ^^^^ TS error: Property 'http' is protected
}

/
├── manifest.json                          # App identity, builders, policies
├── paymentProvider/
│   └── configuration.json                 # Payment methods, connector options
├── service.json                           # Runtime config (memory, timeout, replicas, custom routes)
└── node/
    ├── package.json                       # Dependencies WITH resolutions for TS 3.9.7
    ├── tsconfig.json                      # TypeScript config (skipLibCheck ignored by builder)
    ├── yarn.lock                          # REQUIRED — builder rejects build without it
    ├── index.ts                           # Entry point: exports PaymentProviderService
    ├── connector.ts                       # Class extending PaymentProvider
    ├── clients/
    │   ├── index.ts                       # IOClients with getOrSet
    │   ├── psp.ts                         # ExternalClient for direct PSP calls (cancel/capture/refund)
    │   └── pspSecure.ts                   # SecureExternalClient for card authorization via Secure Proxy
    └── typings/
        └── psp.ts                         # TypeScript interfaces

{
  "builders": {
    "node": "7.x",
    "paymentProvider": "1.x"
  },
  "policies": [
    { "name": "vbase-read-write" },
    { "name": "outbound-access", "attrs": { "host": "api.psp.com", "path": "/*" } },
    { "name": "outbound-access", "attrs": { "host": "api.sandbox.psp.com", "path": "/*" } }
  ]
}

{
  "compilerOptions": {
    "target": "es2019",
    "module": "commonjs",
    "lib": ["es2019"],
    "outDir": "./dist",
    "rootDir": ".",
    "strict": false,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["**/*.ts"],
  "exclude": ["node_modules", "**/node_modules", "dist"]
}

import { IOClients } from '@vtex/api'
import { PspClient } from './psp'
import { PspSecureClient } from './pspSecure'

export class Clients extends IOClients {
  public get psp(): PspClient {
    return this.getOrSet('psp', PspClient)
  }

  public get pspSecure(): PspSecureClient {
    return this.getOrSet('pspSecure', PspSecureClient)
  }
}

import { PaymentProvider } from '@vtex/payment-provider'
import type { Clients } from './clients'

export default class MyConnector extends PaymentProvider {
  // IOContext is at this.context.vtex, NOT this.context directly
  private get account(): string {
    const vtexCtx = (this.context as any).vtex as { account: string; workspace: string }
    return vtexCtx?.account || ''
  }

  private get workspace(): string {
    const vtexCtx = (this.context as any).vtex as { account: string; workspace: string }
    return vtexCtx?.workspace || 'master'
  }

  // Custom clients require a cast
  private get clients() {
    return this.context.clients as any as {
      psp: Clients['psp']
      pspSecure: Clients['pspSecure']
      vbase: import('@vtex/api').VBase
    }
  }

  // VBase is available directly
  private get vbase() {
    return this.context.clients.vbase
  }
}

// node/index.ts
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,
      },
    },
  },
  // Optional: custom routes (e.g., for redirect callbacks)
  // routes: {
  //   myCallback: myCallbackHandler,
  // },
})

{
  "memory": 256,
  "ttl": 10,
  "timeout": 10,
  "minReplicas": 2,
  "maxReplicas": 10,
  "routes": {
    "myCallback": {
      "path": "/_v/my-connector/callback",
      "public": true
    }
  }
}

Helper	Auto-filled from request	Do NOT pass in second argument
`Authorizations.approve(auth, { ... })`	`paymentId`	—
`Authorizations.deny(auth, { ... })`	`paymentId`	`nsu` (not part of deny type)
`Settlements.approve(settle, { settleId })`	`paymentId`, `value`	`value` (already merged from request)
`Refunds.approve(refund, { refundId })`	`paymentId`, `value`	`value` (already merged from request)

// TS 3.9.7 compatible
const baseResponse = Authorizations.approve(authorization, {
  authorizationId: result.authorizationId,
  nsu: result.nsu,
  tid: result.tid,
  acquirer: 'MyPSP',
  code: '200',
  message: 'Approved',
})
const response = {
  ...baseResponse,
  delayToCancel: 21600,
  delayToAutoSettle: 21600,
  delayToAutoSettleAfterAntifraud: 1800,
} as any
return response

// Simple in-memory token cache (TS 3.9.7 compatible)
const tokenCache: Record<string, { token: string; expiresAt: number }> = {}

function getCachedToken(clientId: string): string | null {
  const entry = tokenCache[clientId]
  if (entry && Date.now() < entry.expiresAt) return entry.token
  return null
}

function setCachedToken(clientId: string, token: string, expiresIn: number): void {
  tokenCache[clientId] = {
    token,
    expiresAt: Date.now() + (expiresIn - 300) * 1000,
  }
}

https://{account}.myvtex.com/admin/affiliations/connector/Vtex.PaymentGateway.Connectors.PaymentProvider.PaymentProviderConnector_{connector-name}/

Missing paymentProvider builder or empty/wrong paymentMethods so /manifest and Admin do not list methods correctly.
Build fails with hundreds of TS errors in node_modules/.d.ts files — missing resolutions in package.json to pin type packages to TS 3.9.7-compatible versions.
skipLibCheck: true has no effect — the builder-hub ignores it. Use resolutions instead.
catch (error: any) or other TS 4.x+ syntax in connector code — use the TS 3.9.7 compatible patterns.
configuration.json with invalid fields (usesTestSuite, invented keys) — causes builder validation error.
customFields select options using label instead of text — breaks Admin UI or fails validation.
Missing yarn.lock in the node/ directory — builder rejects the build.
service.json placed inside node/ instead of the project root.
clients: Clients passed directly to PaymentProviderService instead of { implementation: Clients, options: {...} }.
Accessing client.http.post(...) from the connector — http is protected; expose public methods in the client class.
Using SecureExternalClient for cancel/capture/refund — only Create Payment carries secureProxyUrl; post-auth uses ExternalClient.
Accessing this.context.account instead of this.context.vtex.account — the IOContext is nested under .vtex.
Type or install drift (@vtex/api / @vtex/payment-provider) without the clean reinstall path in root and node.
Skipping this.retry(request) and duplicating retry with ad-hoc HTTP — Gateway behavior diverges from PPP.
Card calls without secureProxy, wrong Content-Type, or non-allowlisted destination — Secure Proxy or PCI review fails.
Testing without account allowlisting, without sellable products, or without waiting for master install / payment condition propagation.
Overriding /manifest without VTEX approval or leaving stale x-provider-app after a major version bump.
Homologation ticket missing production endpoint, allowed accounts, or purchase-flow details.
vtex link --no-watch hides compilation errors — prefer watch mode to see full error output.
vtex link on master workspace fails — use a dev workspace (vtex use dev-workspace).
Missing vbase-read-write policy in manifest.json — vbase.saveJSON() returns 403.
Duplicate path segments in PSP base URL — e.g., /checkout/v71/v71/payments when the version is already in the base URL.