Skip to main content
This guide covers the configuration files required for a VTEX payment connector, including the manifest.json file and service-specific settings.

​
Manifest configuration

The manifest.json file is the core configuration file for your VTEX IO app. It defines metadata, builders, policies, and dependencies.

​
Basic structure

manifest.json
{
  "name": "payment-provider-example",
  "vendor": "vtex",
  "version": "1.2.0",
  "title": "Payment Provider Example",
  "description": "Reference app for Payment-Provider protocol implementers",
  "builders": {
    "paymentProvider": "1.x",
    "node": "6.x",
    "docs": "0.x"
  },
  "policies": [
    {
      "name": "vbase-read-write"
    },
    {
      "name": "colossus-fire-event"
    },
    {
      "name": "colossus-write-logs"
    },
    {
      "name": "outbound-access",
      "attrs": {
        "host": "heimdall.vtexpayments.com.br",
        "path": "/api/payment-provider/callback/*"
      }
    }
  ],
  "billingOptions": {
    "type": "free"
  }
}

​
Manifest fields

  • name: Unique identifier for your app (lowercase, hyphens only)
  • vendor: Your VTEX vendor account
  • version: Semantic version (MAJOR.MINOR.PATCH)
  • title: Human-readable name displayed in admin
  • description: Brief description of your connector
{
  "name": "my-payment-connector",
  "vendor": "myvendor",
  "version": "1.0.0",
  "title": "My Payment Connector",
  "description": "Payment connector for MyPaymentGateway"
}
Builders define the capabilities of your app:
  • paymentProvider: Required for payment connectors (use “1.x”)
  • node: Required for backend logic (use “6.x”)
  • docs: Optional, for documentation (use “0.x”)
{
  "builders": {
    "paymentProvider": "1.x",
    "node": "6.x",
    "docs": "0.x"
  }
}
The paymentProvider builder is mandatory for all payment connector apps.
Policies grant permissions to your app:vbase-read-write
  • Allows reading and writing to VBase (VTEX database)
  • Required for persisting payment data
{
  "name": "vbase-read-write"
}
colossus-fire-event
  • Allows firing events to VTEX event system
  • Useful for audit trails and integrations
{
  "name": "colossus-fire-event"
}
colossus-write-logs
  • Allows writing to VTEX logs
  • Essential for debugging and monitoring
{
  "name": "colossus-write-logs"
}
outbound-access
  • Allows HTTP requests to external hosts
  • Required for callbacks and payment gateway communication
{
  "name": "outbound-access",
  "attrs": {
    "host": "heimdall.vtexpayments.com.br",
    "path": "/api/payment-provider/callback/*"
  }
}
You must specify each external host your connector needs to communicate with in the outbound-access policy.
Defines the billing model for your app:
{
  "billingOptions": {
    "type": "free"
  }
}
Available types:
  • "free": No charge
  • "fixed": Fixed monthly fee
  • "variable": Usage-based pricing

​
Adding external API access

If your connector needs to communicate with external payment gateways, add them to the outbound-access policy: 
{
  "policies": [
    {
      "name": "outbound-access",
      "attrs": {
        "host": "heimdall.vtexpayments.com.br",
        "path": "/api/payment-provider/callback/*"
      }
    },
    {
      "name": "outbound-access",
      "attrs": {
        "host": "api.payment-gateway.com",
        "path": "*"
      }
    },
    {
      "name": "outbound-access",
      "attrs": {
        "host": "sandbox.payment-gateway.com",
        "path": "*"
      }
    }
  ]
}

​
Node package configuration

The node/package.json file defines Node.js dependencies and scripts.

​
Required dependencies

node/package.json
{
  "dependencies": {
    "@vtex/payment-provider": "^1.4.0"
  },
  "devDependencies": {
    "@types/node": "^12.0.0",
    "@vtex/api": "6.45.6",
    "typescript": "3.9.7"
  },
  "scripts": {
    "lint": "tsc --noEmit --pretty"
  }
}

​
Key dependencies

1

@vtex/payment-provider

The core payment provider SDK:
  • Provides PaymentProvider base class
  • Includes request/response types
  • Offers helper methods for responses
"@vtex/payment-provider": "^1.4.0"
2

@vtex/api

VTEX IO API SDK (dev dependency):
  • Provides VBase client
  • Includes typing for VTEX services
  • Required for context and client access
"@vtex/api": "6.45.6"
3

TypeScript

TypeScript compiler:
  • Version 3.9.7 recommended
  • Required for type checking
  • Used in lint scripts
"typescript": "3.9.7"

​
Adding additional dependencies

You can add other npm packages as needed: 
{
  "dependencies": {
    "@vtex/payment-provider": "^1.4.0",
    "axios": "^0.21.1",
    "ramda": "^0.25.0"
  }
}
Keep dependencies minimal to reduce bundle size and improve performance.

​
TypeScript configuration

Create a node/tsconfig.json file for TypeScript compiler settings:
node/tsconfig.json
{
  "compilerOptions": {
    "target": "es2017",
    "module": "commonjs",
    "lib": ["es2017"],
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["**/*.ts"],
  "exclude": ["node_modules"]
}

​
Environment-specific configuration

​
Development vs production

Use the this.isTestSuite flag to differentiate between test and production environments: 
export default class MyConnector extends PaymentProvider {
  public async authorize(
    authorization: AuthorizationRequest
  ): Promise<AuthorizationResponse> {
    if (this.isTestSuite) {
      // Test suite logic - simplified responses
      return Authorizations.approve(authorization, {
        authorizationId: 'test-auth-id',
        nsu: 'test-nsu',
        tid: 'test-tid',
      })
    }
    
    // Production logic - real payment gateway integration
    const result = await this.paymentGateway.authorize(authorization)
    return this.mapToVtexResponse(result)
  }
}

​
Accessing custom configuration

Access custom fields configured in configuration.json through the context: 
export default class MyConnector extends PaymentProvider {
  private getClientId(): string {
    return this.context.vtex.settings['Client ID']
  }
  
  private getSecretToken(): string {
    return this.context.vtex.settings['Secret Token']
  }
  
  public async authorize(
    authorization: AuthorizationRequest
  ): Promise<AuthorizationResponse> {
    const clientId = this.getClientId()
    const secretToken = this.getSecretToken()
    
    // Use credentials to authenticate with payment gateway
  }
}

​
Configuration validation

Validate your configuration before deployment:
1

Validate manifest.json

Use the VTEX IO CLI to validate your manifest:
vtex validate manifest.json
2

Type check your code

Run TypeScript compiler to check for errors:
cd node && npm run lint
3

Test locally

Link your app in a development workspace:
vtex link

​
Common configuration issues

Error: Cannot reach external APISolution: Add the external host to outbound-access policy:
{
  "name": "outbound-access",
  "attrs": {
    "host": "api.payment-gateway.com",
    "path": "*"
  }
}
Error: Cannot read/write to VBaseSolution: Add vbase-read-write policy:
{
  "name": "vbase-read-write"
}
Error: Callbacks to VTEX failSolution: Ensure callback URL is in outbound-access:
{
  "name": "outbound-access",
  "attrs": {
    "host": "heimdall.vtexpayments.com.br",
    "path": "/api/payment-provider/callback/*"
  }
}
Error: Type errors during compilationSolution: Ensure all required type packages are installed:
cd node && npm install --save-dev @types/node @vtex/api

​
Next steps

Payment methods

Configure supported payment methods in configuration.json

Creating connector

Learn how to create a connector from scratch

Build docs developers (and LLMs) love

Get started for freeTalk to us