Skip to main content
After thoroughly testing your payment connector, you can publish it to the VTEX App Store to make it available to all VTEX merchants.

​
Prerequisites

Before publishing your connector, ensure you have:
1

Completed testing

Your connector must pass all test suite requirements and have been tested with real transactions in a test environment.See Testing your connector for details.
2

Added billing options

Your manifest.json must include the billingOptions field to make your connector available to all accounts.
If you want to make your connector available to all accounts, you MUST have the billing options field in your manifest.
3

Implemented required routes

All required Payment Provider Protocol routes must be implemented:
  • /manifest
  • /payment-methods
  • /payments (authorize)
  • /settlements
  • /refunds
  • /cancellations
  • /inbounds (optional)

​
Configuring billing options

Add the billingOptions field to your manifest.json:
manifest.json
{
  "name": "payment-provider-example",
  "vendor": "vtex",
  "version": "1.2.0",
  "title": "Payment Provider Example",
  "description": "Reference app for Payment-Provider protocol implementers",
  "billingOptions": {
    "type": "free"
  }
}

​
Billing types

You can choose from different billing models:
TypeDescription
freeNo cost to merchants
fixedFixed monthly/yearly fee
variableUsage-based pricing
For paid connectors, you’ll need to provide additional billing configuration. Contact VTEX support for details on implementing paid billing models.

​
App Store submission process

The publication process follows the standard VTEX App Store submission workflow:
1

Prepare your app metadata

Ensure your manifest.json contains complete information:
manifest.json
{
  "name": "payment-provider-example",
  "vendor": "vtex",
  "version": "1.0.0",
  "title": "Payment Provider Example",
  "description": "Reference app for Payment-Provider protocol implementers",
  "builders": {
    "paymentProvider": "1.x",
    "node": "6.x",
    "docs": "0.x"
  },
  "billingOptions": {
    "type": "free"
  }
}
2

Create documentation

Prepare comprehensive documentation for your connector:
  • Setup instructions
  • Configuration parameters (custom fields)
  • Supported payment methods
  • Testing guidelines
  • Support contact information
Use the docs builder to include documentation in your app.
3

Publish a stable version

Release a stable version (not beta or pre-release):
vtex release patch stable
vtex publish
Follow semantic versioning:
  • Patch (1.0.x): Bug fixes and minor updates
  • Minor (1.x.0): New features, backward compatible
  • Major (x.0.0): Breaking changes
4

Submit for review

Submit your app to the VTEX App Store following the official process:
  1. Go to the VTEX App Store submission page
  2. Fill out the submission form with:
    • App details
    • Description and screenshots
    • Support contact
    • Terms of service (if applicable)
  3. Submit for VTEX homologation
5

Complete homologation

VTEX will review your connector to ensure:
  • It follows the Payment Provider Protocol correctly
  • All required routes are implemented
  • Security best practices are followed
  • Documentation is complete and accurate
The homologation process may take several days to weeks depending on the complexity of your connector.
6

Launch on App Store

After homologation approval, your app will be published to the VTEX App Store at:
https://apps.vtex.com
Merchants can then discover and install your connector.

​
Custom fields configuration

Define the configuration fields that merchants will see when setting up your connector in paymentProvider/configuration.json:
paymentProvider/configuration.json
{
  "name": "TestSuitApprover",
  "paymentMethods": [
    {
      "name": "Visa",
      "allowsSplit": "onCapture"
    },
    {
      "name": "Mastercard",
      "allowsSplit": "onCapture"
    }
  ],
  "customFields": [
    {
      "name": "Client ID",
      "type": "text"
    },
    {
      "name": "Secret Token",
      "type": "password"
    },
    {
      "name": "Currency",
      "type": "select",
      "options": [
        {
          "text": "BRL",
          "value": "1"
        },
        {
          "text": "USD",
          "value": "2"
        }
      ]
    }
  ]
}

​
Custom field types

TypeDescription
textSingle-line text input
passwordMasked password input
selectDropdown with predefined options
toggleBoolean on/off switch
Use the password type for sensitive credentials like API keys and tokens. These values will be encrypted and masked in the admin interface.

​
Required policies

Ensure your manifest.json includes all necessary policies:
manifest.json
{
  "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/*"
      }
    }
  ]
}

​
Common policies

PolicyPurpose
vbase-read-writeStore authorization responses for test suite
colossus-fire-eventSend events to VTEX systems
colossus-write-logsWrite application logs
outbound-accessMake HTTP requests to external services
Add additional outbound-access policies for each external API your connector needs to communicate with (e.g., payment processor APIs).

​
Version management

​
Releasing updates

To release updates to your published connector: 
# For bug fixes
vtex release patch stable

# For new features
vtex release minor stable

# For breaking changes
vtex release major stable

# Publish the new version
vtex publish

​
Deprecating old versions

When releasing breaking changes:
  1. Publish the new major version
  2. Communicate changes to existing users
  3. Provide migration guide in documentation
  4. Maintain support for previous major version during transition period
Merchants using your connector will need to manually update to new major versions. Ensure backward compatibility for minor and patch releases.

​
Post-publication checklist

After your connector is published:
1

Monitor installations

Track which merchants install your connector and monitor for issues.
2

Provide support

Set up support channels for merchants using your connector:
  • Email support
  • Documentation site
  • Issue tracking
3

Gather feedback

Collect feedback from merchants to improve your connector:
  • Feature requests
  • Bug reports
  • Configuration improvements
4

Release updates

Regularly update your connector with:
  • Bug fixes
  • Security patches
  • New features
  • Performance improvements

​
Next steps

Once published, merchants can install and configure your connector:
  • Review Production deployment for merchant setup instructions
  • Monitor your connector’s performance and transaction success rates
  • Maintain compliance with PCI DSS and VTEX security requirements

​
Additional resources

Build docs developers (and LLMs) love

Get started for freeTalk to us