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 check and understand the information in the related links, as well as any prerequisites and settings that need to be in place in 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 (PSP), or simply payment providers, are companies that support electronic transactions with different payment methods, such as credit cards or digital wallets.

To operate in the VTEX environment, payment providers need to be integrated through the Payment Provider Protocol (PPP). This protocol defines the necessary prerequisites and settings that the payment methods available in your connector need to have in order 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 References

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 for all virtual stores within the VTEX ecosystem, whether they be national or 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 wish 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 offers the VTEX Sales App solution. This app enables sales associates to offer a complete and customized in-person experience for each customer, tracking the purchase process from selecting the product to delivering the order.

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 applied to payments with POS

If you want to offer a payment experience in physical stores and on the ecommerce website, you will 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 do not 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 the PCI - DSS Compliance security 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 - Developer Portal
• Secure proxy

If you want to develop your connector using VTEX infrastructure, you can use our VTEX IO, our proprietary development platform. VTEX IO 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 our infrastructure, you can also use our VTEX IO boilerplate, Payment Provider Framework (PPF), which makes creating the connector faster in comparison to using your own infrastructure. With PPF, you do not have to manually configure the API routes, response and request body default 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 or actions that 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 the payment information and places the order directly in the checkout of the VTEX store. This is the most widely used flow type because it allows completing all payment steps 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 do not want to use the native VTEX purchase flow (transparent), you have two options to create custom payment experiences for your customer: Payment App and Redirect.

Payment App

Payment App is an app created in VTEX IO, which enables a payment provider to create a custom payment experience without having to redirect 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:

1. Create a specific app for Payment App.
2. 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 operation 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 login on your platform or even an 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 the VTEX IO.

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

• Payment methods (ecommerce website)

  • Debit, credit, or co-branded cards: Make sure that your connector has the PCI - DSS Compliance 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 these payment methods were 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) in Payment Flow.

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

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

Learn more about Test Suite App 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.

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

The required SLA for homologation is 30 days, which may vary depending on any inconsistencies found in the connector development.

After the homologation process is completed, you will receive a confirmation message and your connector will be available for configuration to VTEX Admin merchants.

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 everyone and Submitting your app to the VTEX App Store.