Skip to main content
This framework is in BETA stage. It’s recommended for connectors with rollout dates at least 3 months away to allow time for investigation and prioritization of any new scenarios.

​
What is the Payment Provider Framework?

The VTEX Payment Provider Framework is a powerful toolkit for building payment connectors that integrate with the VTEX e-commerce platform. It implements the Payment Provider Protocol and provides all the infrastructure you need to process payments securely and efficiently. Built on VTEX IO, the framework handles the complexity of payment processing, allowing you to focus on integrating with your specific payment gateway.

​
Key features

Payment Provider Protocol

Complete implementation of VTEX’s standardized payment protocol with automatic route generation and type-safe interfaces

Multiple payment methods

Support for credit cards, debit cards, bank invoices, and custom payment methods with flexible configuration

Secure Proxy for PCI compliance

Process card payments without PCI certification by routing sensitive data through VTEX’s secure proxy

Split payment support

Built-in capabilities for payment splitting across multiple recipients on authorization or capture

OAuth configuration flow

Streamlined authentication setup with optional OAuth support for merchant onboarding

Async payment handling

Retry mechanism for asynchronous payment flows with automatic callback management

VBase persistence

Integrated state management using VTEX VBase for storing payment data and transaction history

Type-safe development

Full TypeScript support with comprehensive type definitions for all protocol entities

​
How it works

The framework provides an abstract PaymentProvider class that you extend with your custom implementation. Each payment operation (authorize, cancel, refund, settle) is implemented as a method that receives strongly-typed request objects and returns response objects.
node/connector.ts
import { PaymentProvider, AuthorizationRequest, AuthorizationResponse } from '@vtex/payment-provider'

export default class MyPaymentConnector extends PaymentProvider {
  public async authorize(request: AuthorizationRequest): Promise<AuthorizationResponse> {
    // Your payment gateway integration logic
  }
  
  public async cancel(cancellation: CancellationRequest): Promise<CancellationResponse> {
    // Handle payment cancellation
  }
  
  // Additional methods for refund, settle, and inbound webhooks
}
The PaymentProviderService automatically sets up all required routes and handles protocol compliance:
node/index.ts
import { PaymentProviderService } from '@vtex/payment-provider'
import MyPaymentConnector from './connector'

export default new PaymentProviderService({
  connector: MyPaymentConnector,
})

​
Payment flow overview

Here’s how a typical payment transaction flows through your connector:
1

Customer places order

The customer completes checkout and submits payment information through the VTEX storefront
2

Payment authorization

VTEX Gateway calls your connector’s /payments endpoint with an AuthorizationRequest containing payment details
3

Process with gateway

Your connector communicates with your payment gateway to authorize the transaction
4

Return response

Your connector returns an AuthorizationResponse indicating approval, denial, or pending status
5

Settlement (capture)

When the order is invoiced, VTEX calls the /settlements endpoint to capture the authorized amount

​
Supported payment methods

Configure which payment methods your connector accepts in paymentProvider/configuration.json:
paymentProvider/configuration.json
{
  "name": "MyConnector",
  "paymentMethods": [
    {
      "name": "Visa",
      "allowsSplit": "onCapture"
    },
    {
      "name": "Mastercard",
      "allowsSplit": "onCapture"
    },
    {
      "name": "BankInvoice",
      "allowsSplit": "onAuthorize"
    }
  ]
}
Supported payment method names include: Visa, Mastercard, American Express, Diners, Elo, Hipercard, BankInvoice, and more.

​
Architecture benefits

Built on VTEX IO: Leverage the full VTEX IO platform with automatic scaling, monitoring, and deployment pipelines. Type safety: TypeScript interfaces ensure your implementation matches the protocol specification, catching errors at compile time. Security by default: Sensitive card data is tokenized and routed through Secure Proxy, keeping your connector PCI compliant without certification. State management: VBase integration provides reliable persistence for async operations and transaction tracking. Extensibility: Add custom routes, clients, and middleware while maintaining protocol compliance.

​
Get started

Prerequisites

Set up your development environment and install required tools

Quick start

Build your first payment connector in minutes

API reference

Explore the complete API documentation

Testing guide

Learn how to test your connector with the VTEX test suite

​
Community and support

Join the VTEX developer community for help and updates:
Before deploying to production, ensure your connector passes all tests in the VTEX payment test suite. Refer to the Testing guide for complete instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us