Integrating a new payment provider on VTEX

This article is divided into steps that explain the integration flow for a new payment provider on VTEX. Before completing each step and moving on, make sure to review and understand the information in the related links, as well as any prerequisites and settings that must be in place for the current step.

The integration flow of a new payment provider on VTEX has the following steps:

1. Payment Provider Protocol overview
2. Defining the operation environment
3. Selecting the infrastructure type
4. Defining the purchase flow
5. Additional requirements and settings
6. Connector tests
7. Homologation and go-live

The following flowchart shows the possible journeys within the integration process.

Payment service providers (PSPs), or simply payment providers, are companies that support electronic transactions with different payment methods, such as credit cards and digital wallets.

To operate in the VTEX environment, payment providers must be integrated via the Payment Provider Protocol (PPP). This protocol defines the prerequisites and settings that the payment methods available in your connector must meet to work in VTEX stores.

To understand how the Payment Provider Protocol works and the routes used in the payment and authentication flows, see:

• Payment Provider Protocol overview
• Payment Provider Protocol API reference

After making sure you meet the PPP implementation prerequisites, the next step is defining how your connector will work in the VTEX environment.

On VTEX, a payment connector can operate in three different contexts: ecommerce websites, physical stores, or both. Select the option that matches the operating characteristics of your connector.

A payment connector can handle purchases across all virtual stores within the VTEX ecosystem, both national and international.

To process sales in countries other than your home country, check if your payment system meets the financial regulations of every country where you want to operate. In addition, you need to sign a local or global partnership agreement with VTEX. Learn more in Become a VTEX partner.

For payment operations in physical stores, VTEX provides the VTEX Sales App solution. This app enables sales associates to offer a complete, customized in-person experience for each customer, tracking the purchase process from product selection to order delivery.

Connectors developed for VTEX Sales App also use the Payment Provider Protocol (PPP).

To learn more about VTEX Sales App, see:

• VTEX Sales App - Getting started and setting up
• VTEX Sales App - Using the app
• VTEX Sales App - Payments
• Payment Provider Protocol for Point of Sale (POS)

If you want to offer a payment experience in physical stores and on the ecommerce website, you need to configure settings for both cases.

To learn more about this type of operation, in addition to the documentation references linked in previous sections, see Unified Commerce Strategies.

You can develop a single connector configured to work in both environments (physical stores and ecommerce websites). You don't have to create a connector for each type of operation.

When implementing the payment connector on VTEX, you can use the internal infrastructure of your company or our low-code development platform, VTEX IO.

You can develop a connector using your internal infrastructure. In this case, you need to make sure that the architecture allows secure communication between you (payment provider) and the VTEX gateway.

To protect sensitive information, like credit card numbers, during transactions, you need to have a valid Payment Card Industry Data Security Standard (PCI DSS) certification or use Secure Proxy, the VTEX solution that replaces confidential information with encrypted tokens.

To learn more about how to develop the integration (middleware) and transfer sensitive payment information, see:

• Implementing a Payment Provider - Middleware
• PCI DSS Compliance
• Secure Proxy

If you want to develop your connector using VTEX infrastructure, you can use VTEX IO. This platform offers the following advantages:

• Greater integration agility by reusing VTEX templates and clients
• Serverless environment with no need to invest additional financial resources related to infrastructure, reliability, and security management
• Simplified authentication, authorization, and configuration resources that are integrated with all other VTEX systems

If you use the VTEX infrastructure, you can also use our VTEX IO boilerplate, Payment Provider Framework (PPF), which makes creating the connector faster than using your own infrastructure. With PPF, you don't have to manually configure API routes, default response and request body formats, and sensitive information transfer (such as credit card information).

To learn more about development using VTEX IO and how the Payment Provider Framework works, see:

• What is VTEX IO
• VTEX IO CLI
• Payment Provider Framework

A purchase flow represents the steps a customer takes to complete the payment of a purchase. On VTEX, the available purchase flows are transparent or custom (Payment App or Redirect). Select the option that matches the operating characteristics of your connector.

In the transparent purchase flow, the customer enters payment information and places the order directly at checkout in the VTEX store. This is the most widely used flow type because it allows all payment steps to be completed in the same environment, which improves the customer purchase experience.

To learn more about the transparent purchase flow, see What is transparent checkout?.

If you don't want to use the native VTEX purchase flow (transparent), you have two options to create custom payment experiences for your customers: Payment App and Redirect.

Payment App

Payment App is an app built in VTEX IO that enables a payment provider to create a custom payment experience without redirecting the customer to an external page, unlike the redirect purchase flow.

If your connector is being developed using VTEX infrastructure, you can implement Payment App in two different ways:

• Create a specific app for Payment App.
• Use the connector's app. In this case, you have to create a specific React folder for Payment App within the connector app.

Connectors that only operate payments in physical stores are required to use Payment App as the default purchase flow.

To learn more, see Payment App.

Redirect

In this flow, the customer selects the payment option in the VTEX store and is redirected to an external page to complete their payment information. After completing the fields and confirming the payment, the customer is redirected back to the order confirmation screen in the VTEX store.

The redirect flow involves the most friction and the lowest purchase conversion rate, making it the least recommended flow.

To learn more about the redirect purchase flow, see Purchase Flows - Redirect.

Layout modification (optional)

When you implement Payment App or Redirect in your connector, you can also create a non-interactive custom layout (using HTML and CSS) that will be displayed on VTEX Checkout.

To learn how to create a custom payment layout, see Layout Development Guide for payment methods in Smart Checkout VTEX.

In addition to defining the best purchase flow, you need to know the operational and communication patterns between your connector and the VTEX payment gateway. To learn more, see:

• Payment flow - Operations
• Payment flow - Communication

The configuration flow has three endpoints (Create Authorization Token, Provider Authentication, and Get Credentials), designed to improve merchant experience when enabling your connector on the VTEX Admin.

This flow enables the merchant to authenticate in your connector through the VTEX Admin using the appKey, appToken, and applicationId as credentials. Also, you can use this resource to provide other authentication methods for the merchant, such as logging in on your platform or even initial registration.

Implementing a configuration flow is optional. It can be done during middleware creation when you develop the connector using your own infrastructure or with VTEX IO.

Depending on the payment method or features that your connector offers, you might need to meet specific requirements or configure additional settings.

Before adding values to paymentMethods in your connector manifest, check the names already documented in the List Payment Provider Manifest endpoint. If a payment method already exists, use the same name (same spelling and capitalization). Create a new name only when the payment method is truly new.

• Payment methods (ecommerce website)

  • Debit, credit, or co-branded cards: Make sure that your connector has the PCI DSS certification. If you don't have or don't want to use that certification in your connector, you can implement Secure Proxy.

• Payment methods (physical store)

  • Direct credit sale and direct debit sale: Make sure that both payment methods are configured as described in Payment Provider Protocol applied to payments with POS.

• Features

  • Split Payout: This solution enables marketplaces to manage order amounts, and it divides your commission and the amount due to the seller. Learn more in:
    • Split Payouts on Payment Provider Protocol
    • Split Payment
  • Custom Auto Capture: This solution enables the merchant to set a window for automatic capture after the payment is completed. Learn more in Custom Auto Capture Feature.
  • Inbound Request: URL directly connected between the VTEX gateway and the payment provider. Learn more in 6. POST Inbound Request (Beta).

After connector development is complete, you can use the Payment Provider Test Suite to test the following routes:

• Create Payment
• Cancel Payment
• Settle Payment
• Refund Payment

Learn more about Payment Provider Test Suite tests in Testing details.

You can also access your test store to simulate payment of an order before starting the connector homologation process on VTEX.

Homologation is the VTEX certification process that validates a payment provider integration before stores can use it in production.

After completing all previous stages, ensuring that all requirements and settings are in place, and obtaining positive test results, you need to request connector homologation by opening a ticket with VTEX support.

The payment team completes the homologation within 30 days. This period begins only after you submit the Master Partner Agreement for Financial Services (MPA), and it may be longer if any inconsistencies are found during connector development.

After the homologation process is completed, you receive a confirmation message, and merchants can configure your connector in the VTEX Admin.

If you want to increase the visibility of your connector in another channel, you can also publish your connector on the VTEX App Store. Learn more in Making your connector available to process sales and Submitting your app to the VTEX App Store.