This article is a comprehensive guide for partners looking to develop payment connectors compatible with the VTEX platform. It focuses on enabling efficient, standardized integrations that allow connectors to work seamlessly across all stores on the platform.

By following these guidelines, partners can ensure their integrations meet the highest quality standards, delivering value to both merchants and their customers while fostering innovation and competitiveness in digital commerce.

This guide is intended for:

• Payment partner developers and technical teams: For implementing efficient integration solutions.
• Product managers and integration teams: For ensuring the cohesion and effective operation of connectors within the platform.
• Technical support teams from payment providers, gateways, and anti-fraud solutions: For providing ongoing support to maintain the stability and compliance of solutions.

On VTEX, a payment connector is an external service that implements the VTEX Payment Provider Protocol (PPP). This protocol enables communication between the platform and payment providers (such as gateways, acquirers, and anti-fraud solutions), enabling merchants to process transactions in an integrated and standardized way, without the need to build custom integrations.

What you'll find in this guide:

• Mandatory technical requirements
• Benefits of PPP integration
• Connector development phases
• Choosing the infrastructure for the connector
• Best practices in connector development

Partners who want to develop a payment connector on VTEX must implement the following features in their integrations:

• Payment authorization (synchronous or asynchronous).
• Cancellation of authorizations before settlement.
• Settlement (immediate or scheduled).
• Refund after settlement, if the transaction has already been completed.
• Asynchronous transaction status notifications (automatic update of payment status on VTEX).
• Compliance with PCI-DSS, certification, if you want to process payment methods such as credit, debit, or co-branded cards. If you don't have this certification, you must implement the connector using the Secure Proxy solution of VTEX.
• High availability and regional coverage of the connector, in accordance with the provisions set forth in the partnership agreement signed with VTEX.
• Connector endpoints developed according to best practices for API creation.

Implementing connectors using the VTEX Payment Provider Protocol (PPP) offers the following benefits:

• Optimization of technical effort: Reduces the need to develop custom integrations.
• Scalability: You can add new payment methods quickly. Once published, a partner's connector becomes available to all VTEX merchants, increasing the solution's reach and adoption.
• Higher sales conversion: Provides flexibility to adapt to the particularities and specific needs of each merchant.
• Centralized management: Connector configuration can be managed directly in the VTEX Admin.

The development process for a VTEX connector can be divided into four phases:

For more details on the connector creation process, see Integrating a new payment provider on VTEX.

During the API implementation phase, the partner can define the type of infrastructure to use when integrating the connector with VTEX.

See below the characteristics of each available infrastructure option:

Benefits:

• Freedom to choose development tools: Since the infrastructure is fully managed by the developer, they have complete flexibility to select the tools that best meet their needs, such as programming languages, databases, and other technological resources.

• Receiving card data directly in the connector: When developing a connector within your own infrastructure, and in compliance with PCI-DSSstandards, you may receive card data directly if required by the business. This eliminates the need to use features such as the Secure Proxy to capture this information.

Aspects to consider:

• Need for infrastructure maintenance: When developing the connector on your own infrastructure, the development team is responsible for maintaining the system, ensuring scalability, and guaranteeing stability. This increases the workload needed to ensure its proper functioning.

• Less autonomy to make changes: When developing a connector outside the VTEX IO infrastructure, you must contact the VTEX team to request changes such as adding new payment methods or enabling split payments. This process is subject to an SLA defined by the VTEX Payments team and may take up to 30 days.

Benefits:

• Payment Provider Framework (PPF): A complete guide to building connectors using VTEX IO.

• Total flexibility: Can be used for any type of integration, not limited to payment methods. It also allows for easier implementation of additional customizations in the connector when needed.

• Multiple customization options: Supports the creation of frontend components for the Store Framework, including banners on the store homepage, category pages, upsell sections, and more.

• Integrated development with the VTEX ecosystem: Enables the creation of apps that interact with the platform's full set of APIs and events, such as CRM data capture, cart and checkout details, logistics information, and more.

• Real-time event access: Uses the Event Bus to track actions performed on the platform.

• Simplified integration with database as a service: Easily connects to services like VBase and Master data to manage application data efficiently.

• No need for PCI-DSS developers: Connectors built on VTEX IO use Secure Proxy for card data processing, ensuring that the connector doesn't access sensitive information directly. However, the partner organization still needs to be PCI-DSS compliant.

• No infrastructure maintenance: VTEX IO automates all infrastructure management, allowing developers to focus entirely on business logic without dealing with technical infrastructure issues.

• Automated update via app versioning: Connector updates are performed automatically and don't require manual intervention from the VTEX team.

Operational resources:

• Serverless structure: VTEX IO runs directly within the VTEX environment, eliminating the need for external infrastructure.

• GraphQL + REST APIs: Supports multiple communication protocols, offering flexibility for integration.

Aspects to consider:

• No direct access to card data through the connector: VTEX IO isn't compatible with PCI-DSS requirements. As a result, connectors developed on this platform don't have direct access to card data. To process this information, you need to use the Secure Proxy feature. If the business model needs to process card data before sending it to the acquirer, VTEX IO may not be the best option, as it doesn't support this level of access.

• Limitations on supported languages and frameworks: VTEX IO is compatible only with specific technologies, such as React, Node.js, and .NET. Developers unfamiliar with these tools will need to adapt, which may require additional time for learning and adjusting workflows.

• Learning curve for VTEX IO: While VTEX IO is intuitive and user-friendly, it includes specific features that developers need to understand in order to take full advantage of its capabilities. For those without prior experience, it will take some time to adapt and learn the specifities of the platform.

The decision to develop a connector using your own infrastructure or VTEX IO depends on the specific needs of the integration and the level of customization required. The PPP is required for payment methods, while VTEX IO provides greater flexibility for advanced customizations.

When defining the infrastructure, consider the know-how of the team as a strategic factor. Working with familiar technologies reduces risk, speeds up delivery, and improves operational efficiency.

The following are best practices for developing payment connectors. These cover both technical and business aspects that are essential to ensure effective, high-quality integrations. The practices listed below are based on years of collaboration with acquirers, agencies, and anti-fraud providers, always with the goal of delivering reliable, high-performance solutions.

Implementing idempotence in a connector ensures that multiple identical requests with the same parameters produce the same effect, regardless of how many times they are sent. This behavior is essential in critical flows, such as transactional ones. Additionally, VTEX automatically retries identical calls, which can result in multiple requests with the same paymentId to update the transaction status.

Connectors that support idempotency typically show the following operational characteristics:

• Duplicate payments are avoided if the same request is sent again automatically. This behavior ensures that a transaction is processed only once to avoid duplicates. If the connector isn't idempotent, duplicate charges may occur, causing inconsistencies.

• In cases of network (communication) failure, the reliability of the integration is ensured.

• When a merchant or acquirer reports a transactional issue, idempotence ensures that logs and responses are consistent and predictable.

• The number of unnecessary calls to the provider is reduced. If the payment has already been processed, the connector can simply return the previously recorded response, avoiding the need for a new request to the acquirer.

Implementing idempotency

To implement idempotency, the following specifications must be followed when developing the connector:

1. Make sure each transaction has a unique identifier (paymentId).
2. Store and reuse the request response (success, failure, or pending) if the same request is sent again.
3. Set an expiration time for idempotent records.
4. Ensure idempotency also applies to cancellations and refunds.
5. When using the VTEX IO infrastructure:
   • Consider using VBase to store the response based on the paymentId received from the payment gateway through the Create Payment route.
   • When handling a new request, the connector can check VBase to determine whether a similar request has already been recorded. If so, the previously recorded response can be returned. See this implementation example.

In addition to technical reliability, some functional features can significantly increase the commercial impact of a connector. Below, we highlight capabilities that directly contribute to operational success by promoting greater security, efficiency, and conversion.

Support for digital wallets (Apple Pay, Google Pay, PayPal, NuPay)

The growing adoption of digital wallets brings more security and convenience to consumers. Connectors that support these wallets offer the following benefits:

• Smoother checkout: Reduces payment friction, as card details are already stored in the digital wallet.
• Enhanced security: Biometric authentication and tokenization help prevent fraud and reduce chargebacks.
• Higher conversion: Fewer steps during checkout lead to lower cart abandonment rates.

Support for Google Pay with DPAN (Device Primary Account Number) tokenization

Supporting Google Pay with DPAN tokenization offers key advantages for both security and user experience:

• Greater security: Actual card details aren't shared, reducing the risk of fraud.
• Less friction in recurring purchases: DPANs can be reused for recurring payments without needing to request user details again.
• Compatibility with multiple devices: Allows the same card to be used across different devices without requiring re-authentication.
• Reduced fraud costs: Tokenization prevents credential misuse, helping reduce the number of chargebacks.

Support for Google Pay with DPAN is only available through the VTEX native Google Pay Wallet.

Support for payments via POS (VTEX Sales App)

Payment connectors compatible with POS in VTEX Sales App enable Omnichannel transactions between physical and digital environments. Key benefits include:

• Integration between channels: Customers can start a purchase online and complete it in the physical store using the same payment method.
• __Reduction of operational errors:__Since payment is integrated with VTEX Sales App, there's no need to manually record transactions in the ERP.
• Improved shopping experience: Sales associates can process payments quickly within a single system.
• Support for different payment options: The POS can accept credit cards, debit cards, digital wallets, and Pix via QR code (Brazil).

Support for payout split

Connectors with the payout split feature allow automatic division of a transaction amount among different recipients — either at the time of authorization or settlement — depending on the provider's configuration. This feature is essential for marketplaces and omnichannel operations.

• Automated payment distribution: The transaction amount is automatically split, increasing efficiency and reducing operational risk.
• Cost and complexity reduction: Eliminates manual transfers, lowers administrative costs, and speeds up financial reconciliation.
• Flexibility for different business models: Supports operations with models such as marketplace, ship-from-store, and dropshipping.

• VTEX Payment Provider Protocol - Help Center
• Secure Proxy - Help Center
• VTEX Master Data - Help Center
• Implementing a Payment Provider - Dev. Portal
• Payment Provider Framework - Dev. Portal
• Split Payouts on Payment Provider Protocol - Dev. Portal
• PCI-DSS - Dev. Portal
• Payment apps - Dev. Portal
• Whats is VTEX IO - Dev. Portal
• Exemplo de integração: payment-provider-example - GitHub
• Developing services on VTEX IO - Learning Center