Your payment provider app requires two main configuration files: manifest.json for app metadata and paymentProvider/configuration.json for payment-specific settings.
configuration.json Defines your payment provider’s capabilities, supported payment methods, and custom configuration fields displayed in the VTEX Admin.
Location : paymentProvider/configuration.jsonSchema Display name for your payment provider shown in VTEX Admin "name" : "TestSuitApprover"
List of supported payment methods Show Payment method object
Payment method name. Common values:
VisaMastercardAmerican ExpressDinersEloHipercardBankInvoice When split payments are allowed:
onCapture - Split on settlement (typical for credit cards)onAuthorize - Split on authorization (typical for instant payments)disabled - No split payments allowed Custom configuration fields shown in VTEX Admin for merchant setup Field label displayed in Admin (e.g., “Client ID”, “Secret Token”)
Input type:
text - Single-line text inputpassword - Password field (masked)select - Dropdown selectiontextarea - Multi-line text input Options for select type fields Display text for the option
Value stored when option is selected
Example Here’s a complete configuration.json example from the payment provider example app:
{ "name" : "TestSuitApprover" , "paymentMethods" : [ { "name" : "Visa" , "allowsSplit" : "onCapture" }, { "name" : "American Express" , "allowsSplit" : "onCapture" }, { "name" : "Diners" , "allowsSplit" : "onCapture" }, { "name" : "Elo" , "allowsSplit" : "onCapture" }, { "name" : "Hipercard" , "allowsSplit" : "onCapture" }, { "name" : "Mastercard" , "allowsSplit" : "onCapture" }, { "name" : "BankInvoice" , "allowsSplit" : "onAuthorize" } ], "customFields" : [ { "name" : "Client ID" , "type" : "text" }, { "name" : "Secret Token" , "type" : "password" }, { "name" : "Currency" , "type" : "select" , "options" : [ { "text" : "BRL" , "value" : "1" }, { "text" : "USD" , "value" : "2" } ] } ] }
Accessing custom fields Custom fields are accessible via merchantSettings in all request types:
public async authorize ( authorization : AuthorizationRequest ): Promise < AuthorizationResponse > { // Access custom fields by name const clientId = authorization . merchantSettings [ 'Client ID' ] const secretToken = authorization . merchantSettings [ 'Secret Token' ] const currency = authorization . merchantSettings [ 'Currency' ] // Use credentials to authenticate with your payment provider await this.provider.authenticate( clientId , secretToken) }
Custom field names are case-sensitive. Access them exactly as defined in configuration.json.
manifest.json Defines your VTEX IO app’s metadata, builders, policies, and billing configuration.
Location : manifest.jsonSchema App name (lowercase, hyphen-separated) "name" : "payment-provider-example"
VTEX account or vendor name Semantic version (MAJOR.MINOR.PATCH) Human-readable app title "title" : "Payment Provider Example"
Brief description of the app’s purpose "description" : "Reference app for Payment-Provider protocol implementers"
VTEX IO builders and their versions Show Required builders for payment providers
Payment provider builder (use "1.x")
Node.js runtime builder (use "6.x" or higher)
Documentation builder (optional, use "0.x")
"builders" : { "paymentProvider" : "1.x" , "node" : "6.x" , "docs" : "0.x" }
Access policies required by your app Show Common payment provider policies
Read/write access to VTEX Base (key-value storage) { "name" : "vbase-read-write" }
Permission to fire events { "name" : "colossus-fire-event" }
Permission to write logs { "name" : "colossus-write-logs" }
Access to external services (required for payment callbacks) { "name" : "outbound-access" , "attrs" : { "host" : "heimdall.vtexpayments.com.br" , "path" : "/api/payment-provider/callback/*" } }
Add additional outbound-access policies for your payment provider’s API endpoints. Billing configuration for the app Billing model:
free - No chargefixed - Fixed monthly/annual feemetered - Usage-based pricing For non-free apps, additional fields are required. See VTEX IO billing documentation . "billingOptions" : { "type" : "free" }
JSON schema URL for manifest validation "$schema" : "https://raw.githubusercontent.com/vtex/node-vtex-api/master/gen/manifest.schema"
Example Here’s a complete manifest.json example:
{ "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" }, "$schema" : "https://raw.githubusercontent.com/vtex/node-vtex-api/master/gen/manifest.schema" }
Adding external API access To call your payment provider’s API, add outbound-access policies:
{ "name" : "outbound-access" , "attrs" : { "host" : "api.your-payment-provider.com" , "path" : "*" } }
You need separate outbound-access policies for each external host. The callback endpoint to heimdall.vtexpayments.com.br is required for all payment providers.
Environment variables While not strictly configuration files, you can use environment variables for sensitive data that shouldn’t be in configuration.json.
Setting variables Use VTEX CLI to set environment variables:
vtex settings set vtex.payment-provider-example apiEndpoint "https://api.provider.com"
Accessing variables const settings = await this . context . clients . apps . getAppSettings ( '[email protected] ' ) const apiEndpoint = settings . apiEndpoint
Environment variables are account-specific, while customFields in configuration.json are per-merchant-affiliation.