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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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.
metadata
{"track":"payment","tags":["ppf","io-connector","payment-connector","payment-provider-framework","payment-provider","payment-provider-builder"],"version":"1.0","purpose":"Implement PPF connector exposing PPP endpoints by Payment Provider Builder","applies_to":["building a new payment connector in VTEX IO","extend existing payment connector","design a PPF connector correctly"],"excludes":["payment connector hosted outside IO (see payment-provider-protocol)","async callback flows (see payment-async-flow)"],"decision_scope":["override manifest route","use of configurable options"],"vtex_docs_verified":"2026-03-31"}
Payment Provider Framework (VTEX IO)
When this skill applies
Use this skill when:
Creating or maintaining a payment connector implemented as a VTEX IO app (not a standalone HTTP service you host yourself)
Wiring @vtex/payment-provider, PaymentProvider, and PaymentProviderService in node/index.ts
Configuring the paymentProvider builder, configuration.json (payment methods, customFields, feature flags)
Implementing this.retry(request) for Gateway retry semantics on IO
Extending SecureExternalClient and passing secureProxy on requests for card flows on IO
Testing via payment affiliation, workspaces, beta/stable releases, the VTEX App Store, and VTEX homologation
Do not use this skill for:
PPP HTTP contracts, response field-by-field requirements, and the nine endpoints in the abstract โ use payment-provider-protocol
Async undefined status, callbackUrl notification vs retry (IO vs non-IO) โ use payment-async-flow
PCI rules, logging, and token semantics beyond IO wiring โ use payment-pci-security
Decision rules
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.
Hard constraints
Constraint: Builder-Hub uses TypeScript 3.9.7 โ code and dependencies MUST be compatible
The vtex.builder-hub compiles IO apps with TypeScript 3.9.7. It also ignores skipLibCheck: true in tsconfig.json โ every .d.ts file in node_modules is type-checked. This means that even if your own code is valid, a transitive dependency shipping modern .d.ts syntax will break the build with hundreds of errors unrelated to your code.
Why this matters
Agents and developers regularly produce code with TS 4.x+ syntax or install the latest @types/* packages. The build fails with cryptic errors in files the developer never touched, causing many wasted iterations.
Unused variables are errors, not warnings. The builder-hub treats declared-but-unused variables as compilation errors. Avoid destructuring fields you do not use:
// WRONG โ if callbackUrl is not used, build failsconst { paymentId, callbackUrl, value } = authorization
// CORRECTconst { paymentId, value } = authorization
Safe dependency versions (compatible with TS 3.9.7)
Use resolutions in node/package.json to pin transitive dependencies to versions that do not ship modern .d.ts syntax. The **/<package> pattern pins nested copies too.
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
Diagnosing new broken packages: if the build fails with errors in .d.ts files from node_modules, identify the package from the error path, test older versions until you find one without modern syntax, and add it to both devDependencies and resolutions (with **/<package> pattern).
Detection
If the generated code uses any syntax from the table above, or if package.json lacks resolutions for type packages, STOP and fix before attempting vtex link.
Constraint: configuration.json must use only valid schema fields and correct customFields format
The paymentProvider builder validates configuration.json against a strict schema. Unknown fields cause build errors. The customFields[].options array for select type fields must use text and value keys โ never label.
Why this matters
Invalid fields like usesTestSuite or useAntifraud (if not in the current schema) cause immediate vtex link failure. Using label instead of text in select options silently breaks the Admin UI or fails validation.
Canonical fields (verify against current VTEX documentation):
name (required), serviceUrl (auto on IO), implementsOAuth, implementsSplit, usesProviderHeadersName, usesBankInvoiceEnglishName, usesSecureProxy, requiresDocument, acceptSplitPartialRefund, usesAutoSettleOptions, paymentMethods, customFields.
Fields known to break the build:usesTestSuite (does not exist in the schema).
If configuration.json contains keys not in the canonical list, or uses label instead of text in select options, STOP and fix before build.
Constraint: Declare the paymentProvider builder and a real connector identity in configuration.json
IO connectors MUST include the paymentProvider builder in manifest.json and a paymentProvider/configuration.json with a non-placeholder name and accurate paymentMethods. Do not ship the literal placeholder "MyConnector" (or equivalent) as production configuration.
Why this matters
Without the builder, PPP routes and Gateway policies are not wired. A placeholder name breaks Admin, affiliations, and homologation.
Detection
If manifest.json lacks paymentProvider, or configuration.json still uses example placeholder names, stop and fix before publishing.
Constraint: Register PPP routes only through PaymentProviderService with a PaymentProvider implementation
The service MUST wrap a class extending PaymentProvider from @vtex/payment-provider so standard PPP paths are registered. Do not hand-roll the same route surface without the package unless VTEX explicitly prescribes an alternative.
Why this matters
Missed or mismatched routes break Gateway calls and homologation; the package keeps handlers aligned with the protocol.
Detection
If node/index.ts exposes PPP paths manually and does not instantiate PaymentProviderService with the connector class, reconcile with the documented pattern.
// Ad-hoc router only โ no PaymentProviderService / PaymentProvider baseexportdefault someCustomRouterWithoutPPPPackage;
Constraint: PaymentProviderServiceclients field requires { implementation, options } โ not the class directly
When passing custom IOClients to PaymentProviderService, the clients field expects an object with implementation (the class) and options (retry/timeout config), following the ServiceConfig interface from @vtex/api. Passing the class directly causes a runtime error.
Why this matters
This is a common mistake that produces a confusing runtime error instead of a clear type error, since the PPF types may not enforce this strictly.
Constraint: Use this.retry(request) for Gateway retry on IO
Where the PPP flow requires retry semantics on IO, handlers MUST invoke this.retry(request) as specified in the protocol โ not a custom retry helper that bypasses the framework.
Why this matters
"The Gateway expects framework-driven retry behavior; omitting it causes inconsistent authorization and settlement behavior."
Detection
Search payment handlers for protocol retry cases; if retries are implemented without this.retry, fix before release.
Correct
// Inside a PaymentProvider subclass method, when the protocol requires retry:returnthis.retry(request);
Wrong
// Re-implementing gateway retry with setTimeout/fetch instead of this.retryawaitfetch(callbackUrl, { method: "POST", body: JSON.stringify(payload) });
Constraint: Forward card authorization calls through Secure Proxy on IO with allowlisted destinations
For card flows on IO with usesSecureProxy behavior, proxied HTTP calls MUST go through SecureExternalClient (or equivalent VTEX pattern), MUST pass secureProxy set to the secureProxyUrl from the payment request, and MUST target a VTEX-allowlisted PCI endpoint. Only application/json or application/x-www-form-urlencoded bodies are supported. If usesSecureProxy is false, the provider must be PCI-certified and supply AOC for serviceUrl per VTEX.
Why this matters
"Skipping Secure Proxy or wrong content types breaks PCI scope, proxy validation, or acquirer integration โ blocking homologation or exposing card data incorrectly."
Detection
Inspect client code for POSTs that include card tokens without secureProxy in the request config, or destinations not registered with VTEX.
// Direct outbound call with raw card fields and no secureProxyawait http.post("https://acquirer.example/pay", { pan, cvv, expiry });
Constraint: Only Create Payment receives secureProxyUrl โ post-auth operations call the PSP directly
The secureProxyUrl field is present only in the Create Payment (authorize) request. Cancel, capture, and refund operations do not carry card data and do not receive secureProxyUrl. These operations must call the PSP API directly using an ExternalClient (from @vtex/api) with API credentials, protected by outbound-access policies in manifest.json.
Why this matters
Attempting to use SecureExternalClient or secureProxyUrl in cancel/capture/refund handlers will fail because the field is undefined in those requests. This is not a PCI concern โ these operations only reference transaction IDs, not card data.
Detection
If cancel, capture, or refund handlers reference secureProxyUrl or use SecureExternalClient, STOP. These must use ExternalClient with direct HTTP calls to the PSP.
// WRONG โ trying to use SecureExternalClient for captureasyncsettle(settlement: SettlementRequest) {
const client = this.context.clients.pspSecureasPspSecureClient// secureProxyUrl is undefined here โ this will failawait client.capture(settlement.tid, settlement.value, settlement.secureProxyUrl)
}
Constraint: Do not access .http on client instances from outside the client class
The http property on ExternalClient and SecureExternalClient is protected. Calling client.http.post(...) from the PaymentProvider subclass causes a TypeScript compilation error in the builder-hub.
Why this matters
This is a frequent mistake when developers try to make HTTP calls from the connector class instead of through the client's public methods. The builder-hub enforces protected access and fails the build.
Detection
If the connector code accesses .http on a client instance (e.g., this.context.clients.myClient.http.post(...)), STOP. Expose a public method in the client subclass instead.
Correct
// Inside the client class โ this.http is accessible (protected = same class)exportclassPspClientextendsExternalClient {
publicasynccapturePayment(tid: string, amount: number) {
returnthis.http.post(`/v1/payments/${tid}/capture`, { amount })
}
}
// Inside the connector โ call the public methodasyncsettle(settlement: SettlementRequest) {
const clients = this.context.clientsasanyas { psp: PspClient }
return clients.psp.capturePayment(settlement.tid, settlement.value)
}
Note: the builder-hub overrides outDir, rootDir, and paths with its own values. skipLibCheck: true is ignored โ all .d.ts files are checked. Use resolutions in package.json to control dependency type versions instead.
The PPF builder merges its own routes (PPP endpoints) with yours โ you do not need to re-declare the standard PPP routes.
Credentials via affiliation
The PPF maps affiliation headers to connector properties automatically:
VTEX Header
Connector Property
Typical Use
X-PROVIDER-API-AppKey
this.apiKey
PSP Client ID / API Key
X-PROVIDER-API-AppToken
this.appToken
PSP Client Secret / API Token
this.isTestSuite indicates whether the transaction is a test (sandbox).
Custom settings from customFields in configuration.json are available via the authorization object in each request (the exact access pattern depends on the PPF version โ check the types in @vtex/payment-provider).
PPF response helpers โ what each helper fills automatically
When using Authorizations, Settlements, and Refunds helpers from @vtex/payment-provider:
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)
To add delayToCancel with approveCard when the strict type omits it, use a spread with type assertion:
Open the PSP's API Explorer / OpenAPI spec and identify the base URL per environment (test/live).
Do not duplicate version or path segments between baseURL and the operation path (e.g., if the base is https://checkout-test.psp.com/v71, the path for payments is /payments, not /v71/payments).
Validate with a test call (e.g., create payment) before closing the connector implementation.
If the PSP requires an OAuth token, implement in-memory caching of the access token โ the VTEX Gateway has a 2-second timeout on some flows and sequential token + API calls will exceed it.
Replace {connector-name} with ${vendor}-${appName}-${appMajor} (example: vtex-payment-provider-example-v1).
Testing flow summary: publish beta (for example vendor.app@0.1.0-beta โ see Making your app publicly available documentation), install on master, wait ~1 hour, open affiliation, under Payment Control enable Enable test mode and set Workspace (often master), add a payment condition, wait ~10 minutes, place order; then deploy stable and complete homologation.
Replace all example vendor names, endpoints, and credentials with values for your real app before production.
Common failure modes
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.
