{"section":"tutorials","requestedLocale":"en","requestedSlug":"developing-a-payment-connector-for-vtex","locale":"en","slug":"developing-a-payment-connector-for-vtex","path":"docs/en/tutorials/payments/payment-providers/developing-a-payment-connector-for-vtex.md","branch":"main","content":"This article presents the requirements, infrastructure options, and best practices for partners who want to develop [payment connectors](/en/docs/tutorials/what-is-the-connector) compatible with the VTEX platform. The goal is to ensure an efficient, standardized integration that allows connectors to work across all stores on the platform.\n\nThis article is for:\n\n- **Payment partner developers and technical teams:** Build and implement the integrations.\n- **Product managers and integration teams:** Make sure connectors work consistently and run smoothly on the platform.\n- **Technical support teams at payment providers, gateways, and anti-fraud companies:** Provide ongoing support and keep solutions stable and compliant.\n\n## Overview\n\nOn VTEX, a payment connector is an external service that implements the [VTEX Payment Provider Protocol (PPP)](https://developers.vtex.com/docs/api-reference/payment-provider-protocol). This protocol enables communication between the platform and payment providers (such as gateways, acquirers, and anti-fraud solutions), allowing merchants to process transactions in an integrated, standardized way without developing custom integrations.\n\nWhat you'll find in this guide:\n\n- [Technical requirements](#technical-requirements)\n- [Benefits of PPP integration](#benefits-of-ppp-integration)\n- [Connector development phases](#connector-development-phases)\n- [Choosing the infrastructure for the connector](#choosing-the-infrastructure-for-the-connector)\n- [Best practices in connector development](#best-practices-in-connector-development-reliability-and-added-value)\n\n## Technical requirements\n\nPartners who want to develop a payment connector on VTEX must implement the following features in their integrations:\n\n- Payment authorization (synchronous or asynchronous)\n- Authorization cancellation before settlement\n- Settlement (immediate or scheduled)\n- Refunds after settlement\n- Asynchronous transaction status notifications that automatically update the payment status on VTEX\n- [PCI-DSS](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance) certification to process credit, debit, or [co-branded](/en/tracks/payments--6GAS7ZzGAm7AGoEAwDbwJG/1wWt35dRwEboRs1nrSx7G0#store-cards-co-branded) cards, or a connector built with VTEX [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy), which doesn't require this certification\n- High availability and regional coverage of the connector, as defined in the partnership agreement with VTEX\n- Connector endpoints developed following API design best practices\n\n## Benefits of PPP integration\n\nImplementing connectors using the [VTEX Payment Provider Protocol (PPP)](https://developers.vtex.com/docs/api-reference/payment-provider-protocol) offers the following benefits:\n\n- **Optimization of technical effort:** Reduces the need for custom integrations.\n- **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.\n- **Higher sales conversion:** Provides flexibility to adapt to each merchant's unique characteristics and specific needs.\n- **Centralized management:** Connector settings can be managed directly in the VTEX Admin.\n\n## Connector development phases\n\n[Integrating a new payment provider on VTEX](https://developers.vtex.com/docs/guides/integrating-a-new-payment-provider-on-vtex) is the reference guide for the full connector creation process. In short, the partner implements the PPP endpoints, validates the connector with the [Payment Provider Test Suite test cases](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-homologation), and runs [purchase tests](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-framework#placing-an-order-with-your-new-connector) in a test store. When all test cases pass, the partner requests homologation by opening a ticket with [VTEX Support](https://supporticket.vtex.com/support), which requires an active contract and no outstanding payments to VTEX. After the connector is homologated and published, merchants can configure [payment methods](/en/docs/tutorials/registering-gateway-affiliations) for their stores in the [VTEX Admin](/en/docs/tutorials/vtex-admin-start-here).\n\n## Choosing the infrastructure for the connector\n\nWhen implementing the endpoints, the partner chooses whether to host the connector on their own infrastructure or on VTEX IO. Here are the characteristics of each option:\n\n### Own infrastructure\n\n#### Benefits\n\n- **Freedom to choose development tools:** Since the developer fully controls the infrastructure, they can choose the tools that best fit their needs, such as programming languages, databases, and other technologies.\n\n- **Receiving card data directly in the connector:** When developing a connector on your own infrastructure in compliance with [PCI-DSS](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance) standards, you can receive card data directly if the business requires it. This means you don't need features like [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy) to capture this data.\n\n#### Aspects to consider\n\n- **Infrastructure maintenance:** When you host the connector yourself, your development team handles system maintenance, scalability, and stability, which adds to the workload of keeping it running smoothly.\n\n- **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 activating [split](https://developers.vtex.com/docs/guides/split-payouts-on-payment-provider-protocol) payments. This process is subject to an SLA defined by the VTEX Payments team and may take up to 30 days.\n\n### VTEX IO infrastructure\n\n#### Benefits\n\n- **[Payment Provider Framework (PPF)](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-framework):** A complete guide to building connectors on VTEX IO.\n\n- **Use beyond payment methods:** VTEX IO can be used for other types of integrations besides payment methods, and allows you to add custom features to the connector when needed.\n\n- **Multiple customization options:** Allows you to create frontend components for [Store Framework](https://developers.vtex.com/docs/guides/store-framework), such as homepage banners, category pages, upsell sections, and more.\n\n- **Integrated development with the VTEX ecosystem:** Allows you to create apps that interact with all platform APIs and events, such as CRM data capture, cart and checkout details, logistics data, and more.\n\n- **Access to events in real time:** VTEX IO apps can [receive and handle events](https://developers.vtex.com/docs/guides/services-2-handling-and-receiving-events) triggered by actions on the platform.\n\n- **Simplified integration with Database as a Service:** Connects easily to databases such as VBase and [Master Data](/en/docs/tutorials/master-data) to manage your app's data efficiently.\n\n- **Card data handling through Secure Proxy:** Connectors built on VTEX IO must use [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy) to handle card data, so the connector doesn't access sensitive data directly. Since they use Secure Proxy, these connectors don't require [PCI-DSS](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance) certification from the partner.\n\n- **No infrastructure maintenance:** VTEX IO automates all infrastructure management, allowing developers to focus entirely on business logic rather than infrastructure issues.\n\n- **Automatic updates through app versioning:** Connector updates happen automatically, with no intervention needed from the VTEX team.\n\n#### Operational features\n\n- **Serverless architecture:** VTEX IO runs directly in the VTEX environment, so no external infrastructure is needed.\n\n- **GraphQL + REST APIs:** Supports multiple communication protocols for more flexible integrations.\n\n#### Aspects to consider\n\n- **No direct access to card data**: Since the VTEX IO environment isn't [PCI-DSS](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance) certified, connectors developed on it don't access card data directly and must use [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy) to handle it. If your business model needs to process card data before sending it to the acquirer, VTEX IO may not be the best option.\n\n- **Limited language and framework support**: 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.\n\n- **Learning curve for VTEX IO**: [VTEX IO](https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-vtex-io) has specific characteristics, and developers without prior experience on the platform need time to learn them.\n\nIn both options, the connector implements the [PPP](https://developers.vtex.com/docs/api-reference/payment-provider-protocol). The difference lies in hosting and customization: on their own infrastructure, the partner maintains the environment and can receive card data directly, while on VTEX IO the platform manages the infrastructure and offers more resources for advanced customization. The choice depends on the needs of each integration and the desired level of customization.\n\nWhen choosing the infrastructure, consider your team's expertise as a strategic factor. Working with familiar technologies reduces risk, speeds up delivery, and improves operational efficiency.\n\n## Best practices in connector development: reliability and added value\n\nThe following are best practices for developing payment connectors. These cover both technical and business aspects that are essential to ensure effective, high-quality integrations. These practices reflect VTEX's experience from years of collaboration with acquirers, agencies, and anti-fraud providers.\n\n### Technical advantage: Idempotency\n\nImplementing [idempotency](https://en.wikipedia.org/wiki/Idempotence) in a connector ensures that multiple requests with the same parameters have the same effect, regardless of how many times they're sent. This behavior is essential in critical flows, such as payment transactions. Additionally, VTEX automatically retries identical calls, which can result in multiple requests with the same `paymentId` to update the transaction status.\n\nConnectors that support idempotency typically show the following operational characteristics:\n\n- Duplicate charges are avoided when VTEX automatically resends a request, since each transaction is processed only once.\n\n- The integration remains reliable even during network failures.\n\n- When a merchant or acquirer reports a transactional issue, idempotency ensures that logs and responses are consistent and predictable.\n\n- The number of unnecessary calls to the provider is reduced. If the payment has already been processed, the connector can return the previously recorded response, avoiding the need for a new request to the acquirer.\n\n#### Implementing idempotency\n\nTo implement idempotency, follow these guidelines when developing the connector:\n\n1. Make sure each transaction has a unique identifier (`paymentId`).\n2. Store and reuse the request response (success, failure, or pending) if the same request is sent again.\n3. Set an expiration time for idempotent records.\n4. Ensure idempotency also applies to cancellations and refunds.\n5. When using the VTEX IO infrastructure:\n   - Consider using VBase to store the response based on the `paymentId` sent by the payment gateway through the [Create Payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments) endpoint.\n   - 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](https://github.com/vtex-apps/payment-provider-example/blob/main/node/connector.ts#L53).\n\n### Strategic business features\n\nIn 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.\n\n#### Support for digital wallets (Apple Pay, NuPay, Google Pay, PayPal)\n\nThe growing adoption of digital wallets brings more security and convenience to consumers. Connectors that support these wallets offer the following benefits:\n\n- **Smoother checkout:** Reduces payment friction, since card details are already stored in the digital wallet.\n- **Enhanced security:** Biometric authentication and tokenization help prevent fraud and reduce chargebacks.\n- **Higher conversion:** Fewer checkout steps mean lower cart abandonment.\n\n#### Support for Google Pay with DPAN (Device Primary Account Number) tokenization\n\nSupporting Google Pay with [DPAN tokenization](/en/docs/tutorials/dpan-and-fpan-understanding-security-in-the-online-tokenized-payment-flow) offers key advantages for both security and user experience:\n\n- **Greater security:** Actual card details aren't shared, which reduces the risk of fraud.\n- **Less friction in recurring purchases:** DPANs can be reused for recurring payments without asking users for their details again.\n- **Compatibility across devices:** The same card can be used across different devices without re-authentication.\n- **Lower fraud costs:** Tokenization prevents credential misuse, which can reduce chargebacks.\n\n> ⚠️ Support for Google Pay with DPAN is only available through the [VTEX native Google Pay wallet](/en/docs/tracks/google-pay).\n\n#### Support for payments via POS (VTEX Sales App)\n\nPayment connectors compatible with [POS](https://en.wikipedia.org/wiki/Point_of_sale) payments in the [VTEX Sales App](/en/tracks/instore-primeiros-passos-e-configuracoes--zav76TFEZlAjnyBVL5tRc) enable [omnichannel](/en/docs/tracks/unified-commerce-101) transactions across physical and digital channels. Key benefits include:\n\n- **Integration across channels:** Customers can start a purchase online and complete it in the physical store with the same payment method.\n- **Fewer operational errors:** Since payment is integrated with the VTEX Sales App, there's no need to manually record transactions in the [ERP](https://en.wikipedia.org/wiki/Enterprise_resource_planning).\n- **Better shopping experience:** Sales associates can process payments quickly in a single system.\n- **Support for multiple payment options:** The POS can accept credit cards, debit cards, digital wallets, and Pix via QR code (Brazil).\n\n#### Support for payout split\n\nConnectors with the [payout split](/en/docs/tutorials/split-payment#payout-split) feature automatically divide a transaction amount among multiple recipients at authorization or settlement, depending on the provider's configuration. This feature is essential for marketplaces and omnichannel operations.\n\n- **Automated payment distribution**: The transaction amount is automatically split, improving efficiency and reducing operational risk.\n- **Lower costs and complexity**: Eliminates manual transfers, lowers administrative costs, and speeds up financial reconciliation.\n- **Flexibility for different business models**: Supports models such as marketplace, ship from store, and dropshipping.\n\n## Learn more\n\n- [VTEX Payment Provider Protocol - Help Center](/en/docs/tutorials/payment-provider-protocol)\n- [Secure Proxy - Dev. Portal](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy#custom-supported-operators)\n- [VTEX Master Data - Help Center](/en/docs/tutorials/master-data)\n- [Implementing a Payment Provider - Dev. Portal](https://developers.vtex.com/docs/guides/payments-integration-implementing-a-payment-provider)\n- [Payment Provider Framework - Dev. Portal](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-framework)\n- [Split Payouts on Payment Provider Protocol - Dev. Portal](https://developers.vtex.com/docs/guides/split-payouts-on-payment-provider-protocol)\n- [PCI-DSS - Dev. Portal](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance)\n- [Payment apps - Dev. Portal](https://developers.vtex.com/docs/guides/payments-integration-payment-app)\n- [What is VTEX IO - Dev. Portal](https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-vtex-io)\n- [Integration example: payment-provider-example - GitHub](https://github.com/vtex-apps/payment-provider-example)\n- [Developing services on VTEX IO - Learning Center](https://learn.vtex.com/docs/course-service-course-lang-en)"}