[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides payments integration payment app in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/getting-started)

---

Integration Guides

[Back office integration guide (ERP/PIM/WMS)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/erp-integration-guide)

[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/customer-credit-integration-guide)

[External Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/external-marketplace-integration-guide)

[External Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/external-seller-integration-guide)

[Gift Card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/gift-card-integration-guide)

[Headless commerce](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/headless-commerce)

[Login (SSO)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/login-integration-guide)

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/punchout)

[Offer Management Integration Guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/sent-offers-integration-guide-connectors)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-guide)

[Integrating a new payment provider on VTEX](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/integrating-a-new-payment-provider-on-vtex)

[Payment Provider Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-provider-protocol)

[Payment Provider Protocol for Point of Sale (POS) - VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-ppp-applied-to-pos)

[Implementing a Payment Provider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-implementing-a-payment-provider)

[Payment Provider Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-provider-framework)

[Purchase Flows](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-purchase-flows)

[Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app)

[Payment Methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-methods)

[Payment Provider Homologation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-provider-homologation)

[Antifraud Provider Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works)

[PCI - DSS Compliance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-pci-dss-compliance)

[Secure Proxy](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-secure-proxy)

[Split Payouts on Payment Provider Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/split-payouts-on-payment-provider-protocol)

[Layout Development Guide for payment methods in Smart Checkout VTEX](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/layout-development-guide-for-payment-methods-in-smart-checkout-vtex)

[Custom Auto Capture Feature](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/custom-auto-capture-feature)

[Pix: Instant Payments in Brazil](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-pix-instant-payments-in-brazil)

[PSE Payment Method](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/pse-payment-method)

[Google Pay: processing information for payment providers and anti-fraud](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/google-pay-processing-information-for-payment-providers-and-anti-fraud)

[Search Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/search-integration-guide)

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/session-manager)

[Tax Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/tax-service-integration-guide)

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/pricing-hub)

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/recaptcha)

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/getting-started)

---

Integration Guides

[Back office integration guide (ERP/PIM/WMS)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/erp-integration-guide)

[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/customer-credit-integration-guide)

[External Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/external-marketplace-integration-guide)

[External Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/external-seller-integration-guide)

[Gift Card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/gift-card-integration-guide)

[Headless commerce](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/headless-commerce)

[Login (SSO)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/login-integration-guide)

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/punchout)

[Offer Management Integration Guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/sent-offers-integration-guide-connectors)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-guide)

[Integrating a new payment provider on VTEX](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/integrating-a-new-payment-provider-on-vtex)

[Payment Provider Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-provider-protocol)

[Payment Provider Protocol for Point of Sale (POS) - VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-ppp-applied-to-pos)

[Implementing a Payment Provider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-implementing-a-payment-provider)

[Payment Provider Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-provider-framework)

[Purchase Flows](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-purchase-flows)

[Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app)

[Payment Methods](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-methods)

[Payment Provider Homologation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-provider-homologation)

[Antifraud Provider Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works)

[PCI - DSS Compliance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-pci-dss-compliance)

[Secure Proxy](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-secure-proxy)

[Split Payouts on Payment Provider Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/split-payouts-on-payment-provider-protocol)

[Layout Development Guide for payment methods in Smart Checkout VTEX](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/layout-development-guide-for-payment-methods-in-smart-checkout-vtex)

[Custom Auto Capture Feature](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/custom-auto-capture-feature)

[Pix: Instant Payments in Brazil](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-pix-instant-payments-in-brazil)

[PSE Payment Method](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/pse-payment-method)

[Google Pay: processing information for payment providers and anti-fraud](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/google-pay-processing-information-for-payment-providers-and-anti-fraud)

[Search Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/search-integration-guide)

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/session-manager)

[Tax Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/tax-service-integration-guide)

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/pricing-hub)

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/recaptcha)

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides)

Integration Guides

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-guide)

[Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app)

Payment App

> You can check the demo videos of Payment App on our Office Hours through these links in [English](https://read.calvincode.net/reader?url=https://youtu.be/nrZOZ7LMtLE?t=3119) and [Portuguese](https://read.calvincode.net/reader?url=https://youtu.be/YJ0qSgYiN8c?t=1064).

A Payment App is a special type of app built-in [VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-vtex-io) which allows developers to create custom payment experiences on the checkout page, without redirecting customers to an external website.

In terms of programming, a Payment App is defined as a class in TypeScript that extends from [React’s Component](https://read.calvincode.net/reader?url=https://reactjs.org/docs/react-component.html). You can configure a payment method to use a specific Payment App, and this app is instantiated by the Checkout UI when the payment method is selected in the purchase.

The main reasons why someone would choose to build a Payment App over a standard [Payments Integration](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/payments-integration-guide) are that it allows you to:

* Implement a payment method through [Payment Provider Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/payments-integration-payment-provider-protocol) without a redirect flow (without redirecting users to an external website).
* Add a security layer to your store’s online payments using the [3D Secure 2 (3DS2)](https://read.calvincode.net/reader?url=https://help.vtex.com/en/announcements/3ds2-authentication-flow-accept-online-payments-more-securely--6UdTjjVU1AcEQ2aE3Ftxsl) standard.
* Measure conversions by analytics tools for customized flows.

As you can see below, the Payment App is displayed as a modal window when the customer clicks on the **Buy now** button:

![{"base64":"  ","img":{"width":1454,"height":1135,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":1028404,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-payment-app-0.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-payment-app-0.gif)

This tutorial will guide you through the steps required to develop, test, and set up a Payment App in your store. The sections of this tutorial are:
* [Understanding the Payment App flow](#understanding-the-payment-app-flow): An explanation of what a Payment App is, its behavior, and usage.
* [Implementing a Payment App](#implementing-a-payment-app): A step-by-step guide with the basic information needed to develop a Payment App.
* [Operational Mode](#operational-mode): After having deployed the Payment App, check more information about the checkout response. Also, learn how to handle an order payload and how to inject external scripts.

> IO apps do not work in headless environments. If you want to process payments in this type of scenario, you must use a checkout [webview](https://read.calvincode.net/reader?url=https://developer.chrome.com/docs/webview) or implement a fully headless integration directly between your system and the acquirer/connector, sending the information via custom payments or promissory notes.

## Understanding the Payment App flow

Our Payment App model applies to a large variety of payment methods thanks to its interaction with the Checkout API, as shown in the following sequence diagram:

![{"base64":"  ","img":{"width":1082,"height":759,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":73948,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-payment-app-1.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-payment-app-1.png)

Below is described the flow in the same order of the sequence diagram (steps from 1 to 4 are the same for every payment flow; steps unique to the Payment App flow are from 5 onwards):
1. Checkout UI sends a Start Transaction request to the Checkout API.
2. Checkout API sends a [Start Transaction request](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/1createanewtransaction) to the Gateway API.
   * VTEX Payment Gateway creates the new transaction and generates a unique `transactionId`, which is returned to the Checkout, and then to the Checkout UI.
3. Checkout UI sends a [Send Payments request](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/2sendpaymentspublic) directly to the Gateway API.
   * The Gateway will create, for each payment, a payment entity inside the transaction entity that was created in the previous request. Note that, for multiple payments, they are all sent in this same request. That is, one transaction can have multiple payments. For each payment entity, a `paymentId` is generated and all of them are returned to the Checkout UI. This step sends the actual payment information (i.e.: credit card data).
4. Checkout UI sends an Authorization request to the Checkout API.
5. Checkout API encapsulates two requests to the Gateway API.
   * The first is the [Send Additional Data request](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/3sendadditionaldata) that sends to the Gateway API information about the order, such as the client profile data, the shipping address, and the cart information (cart items). Such information is securely stored in the Gateway database, and this information is used by anti-fraud providers, and also used by a few payment providers to Authorize the transaction.
   * The second is the actual [Authorization request](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/4doauthorization) that the Checkout API performs to the Gateway API. This request will trigger the Payment Authorization workflow inside the Gateway API.
         1. The Gateway API calls the [Create Payment request](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/reference/createpayment) for the correct connector depending on the Payment Conditions that was set up by the store administrator.
         2. At this point, the connector handles the request and performs its logic depending on the Payment method. Using Pix as an example, the connector will request the Payment Provider to create a payment in their API and will receive the necessary information to build the Pix QR Code.
         3. The connector responds the Create Payment request to the Gateway. The body of the response has a `paymentAppData` field, which contains two properties. The first is `appName`, which describes the name of the VTEX account responsible for developing, maintaining and distributing the app, and the name of the Payment App that will be used in the transaction (e.g., `"{vendor}.{appName}"` ). The second is `payload` containing the payload to complete the transaction (i.e.: the information to build the Pix QR code). Then, the Gateway responds to the Checkout API and it responds back to the Checkout UI which instantiates the Payment App with the corresponding payload that was generated in the connector.
6. The Checkout UI instantiates the Payment App defined by the `paymentAppData.appName` and adds to the app object the `appPayload` property and fills this property with the content of `paymentAppData.payload`. Then the Payment App can perform its logic here. For instance, it could be an Authorization App (3DS v2) or a QR Code (Pix), or it could simulate a redirection inside the Payment App frame. At this point, the transaction is in Authorizing state (more information about transaction status can be found in the [Transaction flow in Payments](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/transaction-flow-in-payments--Er2oWmqPIWWyeIy4IoEoQ) article).
7. When the user finishes the interaction, the Payment App closes and it will trigger the transaction Validation in the Checkout UI, which starts the validation where the Checkout UI gets the transaction status from the Checkout API (which will [request the transaction status](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/transactiondetails) from the Gateway API). If the transaction status is **Authorized** or **Undefined** then the Checkout UI displays the Order Placed screen. Else, the Checkout UI shows a warning and returns to the state where the user can choose the payment method.

## Implementing a Payment App

The following tutorial will guide you through the steps required to implement a Payment App, including:

* Information on how to set up a development environment.
* Steps to clone the repository that contains a Payment App boilerplate code for you to edit.
* How to run and test your Payment App.
* Information about the deployment process.

To proceed with the following steps, you will be using the [VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-vtex-io) development platform.

> If you are implementing a new payment method in your Payment App, please contact the [VTEX Support Team](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/opening-tickets-to-vtex-support) to add it to the VTEX backend.

### Step 1: Setting up the development environment

1. Using your computer system terminal, [install the VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference) (Command Line Interface).
2. After installing VTEX IO CLI, check the documentation [Creating a Development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-development-workspace) to create a workspace and start developing the Payment App.
3. When you finish creating the workspace, jump to the next section.

### Step 2: Developing your Payment App

These are the minimum things you need to change in the boilerplate and make your own app.

In addition to these modifications, you need to add the business logic of your payment system.

> Before you start editing the Payment App, it is necessary to have Git installed on your computer. Click [here](https://read.calvincode.net/reader?url=https://git-scm.com/downloads) to learn more.

1. Using your terminal, clone the repository that contains a Payment App model to your local files by running:

`1

git clone https://github.com/vtex-apps/example-payment-authorization-app.git

`

1. After cloning the repository, use a code editor of your choice to open the project locally.
2. Open the `manifest.json` file and update its content according to your scenario. If you need more information about the required fields, access our [Manifest documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest). The value set in the `name` field will be the unique identifier for this app and must be the exact name that corresponds to the response of your connector (`appname` property of `paymentAppData` field in the response body of the Create Payment endpoint). The `billingOptions` field is also required and set with the property `type` as `free`. More information about the `billingOptions` field can be found in the [Billing Options article](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-billing-options).
3. After finishing the update, open the `pages/pages.json` file and replace `example-payment-auth-app` with the app `name` set in `manifest.json`. The `pages.json` file is responsible for creating the routes for your application. So it is necessary to make this configuration for the VTEX system to find and display the app at checkout. Also, the `"component"` field having the `"index"` value indicates that the `index.js` file in the `react` folder is the file with the component that will be instantiated at checkout.

> Replace only the last part of the path in the `pages.json` file for the name of your app. In this case, the `example-payment-auth-app` part. Do not change the beginning of the path `checkout/transactions/`, since the checkout uses it to identify a payment application.\\n\\nAlso, if you are using the **Test Connector** to make internal tests with your app, you have to keep the original name of the app that came from the repository in the `pages.json` file, since it will be the reference for this connector to open the Payment App in the checkout.

1. Using your terminal, go to the app directory and run the following command:

`1

vtex link

`

Once you [link the app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-linking-an-app), your local computer files will sync to our cloud development environment. It means that any change done locally in the code you are working on will be sent to the cloud and reflected in the workspace.

### Step 3: Testing a Payment App flow

A Payment App will appear on the checkout screen by following the steps below, allowing you to test the Payment App general flow.

> Proceed with the following steps only when you want to test a Payment App flow; otherwise, skip to [Step 4: Deploying the Payment app](#step-4-deploying-your-payment-app).

1. Make sure you have your connector installed in your account configured with the Payment App and the payment method you want to test in your Payment App. The connector must contain the field `paymentAppData` in the response body of the [Create Payment endpoint](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/reference/createpayment) with the right properties (`"appName": "{vendor}.{appName}"` and `"payload": "{payload information}"`). If you do not have the connector installed yet, contact the [VTEX Support Team](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/opening-tickets-to-vtex-support) to help you with the installation process. More information about how the endpoints should be implemented can be found in the article [Implementing a Payment Provider](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/payments-integration-implementing-a-payment-provider).
2. Select the payment condition associated with your connector in the checkout and finish the purchase to test the flow.

### Step 4: Deploying your Payment App

Once you finish the changes, follow our documentation on [Making your new app version publicly available](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available) to run your app on the **Master** workspace.

## Operational Mode

If you followed all the previous steps, it means that you successfully created a Payment App and are ready to take advantage of the benefits of having an additional verification step to the checkout of your store.

This section discusses the following topics to help you make the best use of the Payment App:

* Handling the order payload.
* Understanding the response to the Checkout UI.
* Injecting external scripts.

### Handling the order payload

The `appPayload` is what the Payment App receives as props, and it consists of a serialized JSON of the order payload. This variable is not declared in the Payment App class, but it is added to its `props` after the Payment App is instantiated in the Checkout UI. You can access this information with the following code:

`1

const { appPayload } = this.props // This appPayload is a serialized JSON (as string).

`

The expected content is a JSON object consisting of the Payment App’s data needed for the Payment App to allow or deny an order placement. Thus, the `appPayload` fields will be defined by the developer of the associated connector.

To exemplify how the payload can be used, take the following example:

`1

{

2

 "timeToCancel": 300,

3

 "transactionApproveLink": "https://..."

4

}

`

In this example, there are two fields for illustration. The first field (`"timeToCancel"`) can mean the amount of time after the payment app stays open before automatically canceling the transaction. The second field (`"transactionApproveLink"`) can have a link to request for the approval of the transaction if all the conditions in the Payment App are fulfilled.

### Understanding the response to the Checkout UI

When the Payment App finishes its operation, it has to inform the Checkout UI that it should be closed and then check if the transaction is approved or not. If the transaction is `approved` or `undefined`, the Checkout UI will redirect the user to the Order Placed page; otherwise, it will show a warning pop-up and then take the user back to the payment options.

To perform these steps, the Checkout UI listens to the `transactionValidation.vtex` event that is triggered by the Payment App using the [browser’s native event handling engine](https://read.calvincode.net/reader?url=https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building%5Fblocks/Events) during the validation step. When this event is triggered, the Checkout UI will close the Payment App and check the transaction status from the Gateway. The following [example method](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/example-payment-authorization-app/blob/master/react/index.tsx%23L45) can be used by the Payment App to trigger the event:

`1

respondTransaction = () => {

2

 $(window).trigger('transactionValidation.vtex')

3

}

`

> If the `transactionValidation.vtex` event is not triggered, the order confirmation email will not be sent to the user. We recommend that you create a retry flow to act in cases where this event is not triggered or the order confirmation email is not sent.

### Injecting external scripts

An external script injection allows your Payment App to have additional content and behavior. To run external scripts on your Payment app, you need to inject the following script on the `head` of the checkout `html`. To do so, you have to do a DOM injection as follows:

`1

const head = document.getElementsByTagName('head')[0]

2

3

const js = document.createElement('script')

4

js.id = {{script-id}}

5

js.src = {{script-src}}

6

js.async = true;

7

js.defer = true;

8

js.onload = {{callback-onload}}

9

10

11

head.appendChild(js)

`

There is an example of script injection [here](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/example-payment-authorization-app/blob/master/react/index.tsx%23L89) that inserts Google Recaptcha to a Payment App.

> Keep in mind that if the external `js` script handles DOM manipulation, you should use [React's Ref](https://read.calvincode.net/reader?url=https://reactjs.org/docs/refs-and-the-dom.html) to create a `div` container and hand it over to the library. You can find an [example here](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/example-payment-authorization-app/blob/master/react/index.tsx%23L106).

## Payment App Scenarios

In the following sections, you will find some scenarios in which you can use a Payment App.

### Scenario 1: An integration via Payment Provider Protocol that requires a new payment method

The best way to create a new payment method is by developing a Payment App, once it allows customers to complete the payment transaction without leaving the checkout page. It also allows you to add a security layer to your store’s online payments by using the [3D Secure 2](#scenario-2-payment-app-and-3d-secure-2) standards.

### Scenario 2: Payment App and 3D Secure 2

The [3D Secure 2](https://read.calvincode.net/reader?url=https://3dsecure2.com/) is a protocol that allows a website’s checkout process to comply with the [Strong Customer Authentication (SCA)](https://read.calvincode.net/reader?url=https://3dsecure2.com/glossary/%23what-is-strong-customer-authentication-sca) requirements by performing risk-based authentication to approve an online card transaction. It was created to attend to the [Revised Payment Service Directive 2 (PSD2)](https://read.calvincode.net/reader?url=https://3dsecure2.com/glossary/%23what-is-payment-service-directive-2) regulations in Europe.

The 3D Secure 2 (3DS2) is an evolution of the 3D Secure 1 (3DS1). It introduces the [frictionless authentication flow](https://read.calvincode.net/reader?url=https://3dsecure2.com/glossary/%23what-is-frictionless-flow) and improves the purchase experience compared to 3DS1\. More details about the differences between 3DS1 and 3DS2 can be found in the [3D Secure 2 FAQ](https://read.calvincode.net/reader?url=https://3dsecure2.com/frequently-asked-questions/%23what-are-the-main-changes-in-3d-secure-2).

> On VTEX, [3D Secure 2](https://read.calvincode.net/reader?url=https://3dsecure2.com/) can only be implemented through the Payment App, as the platform doesn't support alternative methods such as redirect URLs for this protocol.

#### 3DS2 flow

To apply the 3DS2 to the checkout, the acquirer that processes the website payments needs to create a Payment App that will handle challenges for each [issuing Bank](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/what-is-the-issuing-bank--7aVIVGwgtU4SWuqowSQksg) that will use the Strong Authentication through the 3DS2.

When the customer adds the credit card information and clicks on the Checkout button, the acquirer will call the issuing bank through the 3DS2 flow.

The card issuer will, in turn, analyze the fraud context of that purchase (the score, probability), also called [Risk-based Authentication](https://read.calvincode.net/reader?url=https://3dsecure2.com/frictionless-flow/%23what-is-risk-based-authentication). The score will be a result of a series of risk-based elements which can include the value of the purchase, transactional history, device information, among others. If this analysis returns as a score for high fraud risk, the provider can choose to call the 3DS2 challenge asking the customer to proceed with the Strong Authentication method (i.e.: approve the payment in the bank app). If it falls in a score for low fraud risk, the provider will not call the challenge.

If the acquirer decides that it must perform the Strong Authentication for any payment, it must return to VTEX, in the response body of the [Create Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments) route, his `status` as `undefined` and his Payment App information in the `paymentAppData` field.

The `status` returned as `undefined` indicates to our Gateway that the payment has not yet been authorized or denied. There may be several reasons for this, with Strong Authentication being one of them. What will make the Payment App, which runs 3DS2, be called is the `paymentAppData` field in the response.

The Gateway will save this app data on the payment and tell the Checkout that payment has not yet been authorized or denied. It will make the Checkout UI run the Payment App specified in the `paymentAppData` field.

Once the Payment App opens, the Strong Authentication warning will be displayed to the customer within the Payment App on the checkout screen. It will require the customer to approve the transaction from his account on the issuing Bank (i.e.: in the bank app).

After finishing the interaction with the Payment App, the app closes and redirects the customer depending on the `status` of the transaction. If it is `approved` or still is `undefined`, it will go to the order placed screen. If it is `denied` or `canceled`, the Checkout UI shows a warning and returns to the state where the user can choose the payment method.

The following image shows how the 3DS2 is displayed to customers:

![{"base64":"  ","img":{"width":1999,"height":1245,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":288965,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-payment-app-2.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-payment-app-2.png)

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F87548049%3Fv%3D4%26w=64%26q=75)](https://github.com/ricardoaerobr)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7108339%3Fv%3D4%26w=64%26q=75)](https://github.com/brunoamui)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Integration-Guides/payments-integration-guide/payments-integration-payment-app.md)

[Purchase Flows« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app//docs/guides/payments-integration-purchase-flows)[Payment MethodsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app//docs/guides/payments-integration-payment-methods)

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F87548049%3Fv%3D4%26w=64%26q=75)](https://github.com/ricardoaerobr)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7108339%3Fv%3D4%26w=64%26q=75)](https://github.com/brunoamui)

ON THIS PAGE

[Understanding the Payment App flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23understanding-the-payment-app-flow)

[Implementing a Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23implementing-a-payment-app)

[Step 1: Setting up the development environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23step-1-setting-up-the-development-environment)[Step 2: Developing your Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23step-2-developing-your-payment-app)[Step 3: Testing a Payment App flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23step-3-testing-a-payment-app-flow)[Step 4: Deploying your Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23step-4-deploying-your-payment-app)

[Operational Mode](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23operational-mode)

[Handling the order payload](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23handling-the-order-payload)[Understanding the response to the Checkout UI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23understanding-the-response-to-the-checkout-ui)[Injecting external scripts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23injecting-external-scripts)

[Payment App Scenarios](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23payment-app-scenarios)

[Scenario 1: An integration via Payment Provider Protocol that requires a new payment method](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23scenario-1-an-integration-via-payment-provider-protocol-that-requires-a-new-payment-method)[Scenario 2: Payment App and 3D Secure 2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23scenario-2-payment-app-and-3d-secure-2)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Integration-Guides/payments-integration-guide/payments-integration-payment-app.md)

Copy page

On this page

ON THIS PAGE

[Understanding the Payment App flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23understanding-the-payment-app-flow)

[Implementing a Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23implementing-a-payment-app)

[Step 1: Setting up the development environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23step-1-setting-up-the-development-environment)[Step 2: Developing your Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23step-2-developing-your-payment-app)[Step 3: Testing a Payment App flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23step-3-testing-a-payment-app-flow)[Step 4: Deploying your Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23step-4-deploying-your-payment-app)

[Operational Mode](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23operational-mode)

[Handling the order payload](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23handling-the-order-payload)[Understanding the response to the Checkout UI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23understanding-the-response-to-the-checkout-ui)[Injecting external scripts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23injecting-external-scripts)

[Payment App Scenarios](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23payment-app-scenarios)

[Scenario 1: An integration via Payment Provider Protocol that requires a new payment method](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23scenario-1-an-integration-via-payment-provider-protocol-that-requires-a-new-payment-method)[Scenario 2: Payment App and 3D Secure 2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app/docs/guides/payments-integration-payment-app%23scenario-2-payment-app-and-3d-secure-2)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides vtex io documentation toolbelt in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/updates/release-notes)

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/updates/release-notes)

VTEX IO CLI

VTEX IO CLI is a **command-line interface** that gives you access to every feature of the VTEX platform.

You can use the VTEX IO CLI to:

* List, install or uninstall apps available in your account.
* List, create, promote or remove [**workspaces**](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-workspace).
* Develop new apps in [**link mode**](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-linking-an-app), using automatic synchronization.
* [**Release**](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-releasing-a-new-app-version), [**publish**](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-publishing-an-app) and **deploy** new app versions.

To install it and learn more about its functionalities, check the [**VTEX IO CLI**](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference) reference section.

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Reference/concepts/vtex-io-documentation-toolbelt.md)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-toolbelt/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Reference/concepts/vtex-io-documentation-toolbelt.md)

Copy page

On this page

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] How do I use the VTEX b2b admin customers app? Provide documentation and configuration details.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/vtex-io-deprecated-apps)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/guides/vtex-io-deprecated-apps)

---

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/vtex-io-apps)

⚠ Warning ⚠

Official extension

Version: 2.0.1

Latest version: 2.0.1

_This is a fork of the [vtex.admin-customers](https://read.calvincode.net/reader?url=https://github.com/vtex/admin-customers) to keep the integration with B2B Suite_

# Customers Admin

A VTEX admin app that helps the management of your customer data. This application allows the user to create, edit and search for customers. It's an alternative for MasterData when it comes to managing the documents from CL entity.

The [vtex.admin-customers-graphql](https://read.calvincode.net/reader?url=https://github.com/vtex/admin-customers-graphql) is a dependence of this application. Its responsibility is to group all the GraphQL queries and mutations that are needed to manage data from MasterData.

## 🚀 Installation

Using [VTEX IO Toobelt](https://read.calvincode.net/reader?url=https://vtex.io/docs/recipes/development/vtex-io-cli-installation-and-command-reference/%23command-reference) log into the VTEX account you are working on and install the latest version:

`1

vtex install vtex.b2b-admin-customers

`

If everything went well, you can find the app by acessing **Admin > Customers > Customers** or acessing the URL `/admin/customers`

## ✅ Features

The list below presents every feature of this application, where the ones that are checked are already implemented. The features that are yet to come are unchecked.

> Please, whenever a new feature from the list below is implemented, mind marking the checkbox and create a feature demo.

* [Listing](#listing)
* [Memorize visibility fields](#memorize-visibility-fields)
* [Search](#search)
* [Filters](#filters)
* [Creation](#creation)
* [Details view](#details-view)
* [Edition](#edition)
* Deletion of profile (GDPR/LGPD)
* Address association listing
* Schema viewing with user-level configuration
* Counters

## 🎥 Demonstration

**Listing**

![{"base64":"  ","img":{"width":1912,"height":935,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":3299212,"url":"https://user-images.githubusercontent.com/17439470/127700770-fedd9c66-5112-4bc7-9f85-c43117e8c355.gif"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/17439470/127700770-fedd9c66-5112-4bc7-9f85-c43117e8c355.gif)

**Memorize visibility fields**

The visibility fields is a feature to toggle visibility of table columns.

Here we have an additional feature that saves the preferred column visibility configuration of the end user, maintaining your configurations even after a page refresh and future visits to this page.

![{"base64":"  ","img":{"width":1912,"height":937,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":1358706,"url":"https://user-images.githubusercontent.com/17439470/127700866-92656fe0-1f8a-4b4d-8e3c-2d4a2a736778.gif"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/17439470/127700866-92656fe0-1f8a-4b4d-8e3c-2d4a2a736778.gif)

**Search**

The search input uses the fields: **E-mail**, **First Name** or **Last Name** to filter the results that matches the terms searched while also displaying the results on the table.

![{"base64":"  ","img":{"width":1912,"height":938,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":389613,"url":"https://user-images.githubusercontent.com/17439470/127700895-78509248-fc5b-4036-b45c-cee8fa7f0509.gif"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/17439470/127700895-78509248-fc5b-4036-b45c-cee8fa7f0509.gif)

**Filters**

With these filters it is possible refine your search. You can filter by: **E-mail**, **First Name**, **Last Name**, **Document ID**, **Document** or **Receive Newsletter**.

Every filter has conditionals for you to choose from, it could be **equal**, **not equal** or **contains**.

![filters 1](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/17439470/127700913-dbb54e5c-4327-4df6-9e4d-022b6fa34c3f.png)![filters 2](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/17439470/127700917-a4d5dcac-56fb-491c-b7af-adaea10d2cc6.png) **Creation**

![{"base64":"  ","img":{"width":1903,"height":931,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":2315179,"url":"https://user-images.githubusercontent.com/17439470/127700937-27bde86b-7825-4a75-b32a-20bae727f41a.gif"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/17439470/127700937-27bde86b-7825-4a75-b32a-20bae727f41a.gif)

**Details view** ![detail](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/17439470/127700959-633b02c0-0eb8-4159-a81d-586cbf5ce65b.PNG) **Edition**

![{"base64":"  ","img":{"width":1912,"height":932,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":913163,"url":"https://user-images.githubusercontent.com/17439470/127700969-7b58c9f9-cb65-4fd3-b605-739e9576f020.gif"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/17439470/127700969-7b58c9f9-cb65-4fd3-b605-739e9576f020.gif)

## ☕ Developing

1. Clone this repo `git clone https://github.com/vtex/admin-customers`
2. `yarn --cwd react/` for code completion
3. `vtex link`
4. Navigate to `workspace--account.myvtex.com/admin/app/example`

See also

[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Customers Admin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/apps/vtex.b2b-admin-customers%23customers-admin)

[🚀 Installation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/apps/vtex.b2b-admin-customers%23-installation)

[✅ Features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/apps/vtex.b2b-admin-customers%23-features)

[🎥 Demonstration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/apps/vtex.b2b-admin-customers%23-demonstration)

[☕ Developing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.b2b-admin-customers/docs/apps/vtex.b2b-admin-customers%23-developing)

Was this helpful?

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides search overview in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/getting-started)

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/catalog-overview)

[Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/marketplace-overview)

[Orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/orders-overview)

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/checkout-overview)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/payments-overview)

[Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/fulfillment)

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview)

[Pricing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/pricing-overview)

[Promotions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/promotions-overview)

[Subscriptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/subscriptions)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/getting-started)

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/catalog-overview)

[Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/marketplace-overview)

[Orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/orders-overview)

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/checkout-overview)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/payments-overview)

[Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/fulfillment)

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview)

[Pricing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/pricing-overview)

[Promotions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/promotions-overview)

[Subscriptions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/subscriptions)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/master-data)

---

Payments

---

Orders

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides)

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/getting-started)

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview)

Search

> **Help us improve our documentation!** Tell us about your experience with this article by filling out [this form](https://read.calvincode.net/reader?url=https://forms.gle/fQoELRA1yfKDqmAb8).

Intelligent Search is a [VTEX IO](https://read.calvincode.net/reader?url=https://vtex.com/us-en/store-framework/) alternative to Legacy Search. It assists the customer in their purchase journey and presents results from the first interaction with the search bar. The tool displays search and product suggestions that may interest the user. Intelligent Search also corrects spelling errors and understands words not contained in the product information.

## Setting up the Intelligent Search

### Search

The [VTEX Search app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-search) is responsible for handling the new [Intelligent Search](https://read.calvincode.net/reader?url=https://help.vtex.com/tracks/vtex-intelligent-search) solution in IO stores by providing new UI components that enhance the search experience, such as the autocomplete feature.

![{"base64":"  ","img":{"width":1200,"height":514,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":413394,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/search-overview-0_21.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/search-overview-0_21.gif)

### Intelligent Search API

The [Intelligent Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/intelligent-search-api%23overview) allows you to consult the information about the user's search in your store and its terms. You can also access information about banners, facets, and suggested terms.

## Customizing the search experience of your store

### Search Result

[VTEX Search Result app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-search-result) is responsible for handling the result fetched by the [Intelligent Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/intelligent-search-api%23overview) and displaying it to users. The app exports all store blocks expected in a search results page, such as the filters and the product gallery.

![{"base64":"  ","img":{"width":2878,"height":1578,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":746685,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/search-overview-1_33.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/search-overview-1_33.png)

### Search Bar

The [Search Bar component](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-store-components-searchbar) shows a search bar with autocomplete options and displays the matching products.

![{"base64":"  ","img":{"width":1892,"height":694,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":884048,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/search-overview-2_39.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/search-overview-2_39.png)

### Autocomplete

The [Autocomplete](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-search-autocomplete) is an alternative for the default VTEX autocomplete. The functionality displays previous search results based on current and previous searches. These results are presented in four different lists, which can be together or separated, depending on the customer's interaction.

![{"base64":"  ","img":{"width":1528,"height":692,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":320801,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/search-overview-3_45.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/search-overview-3_45.png)

### Banners

[Banners](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-search-banner) are the functionality responsible for displaying banners as promotional actions on the customer's search result page. This process is done by associating the words and filters selected when searching for these banners.

### Suggestions

[Suggestions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-search-suggestions) is a component used to suggest search terms similar to the current query.

### DidYouMean

[DidYouMean](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-search-didyoumean) is a component used to suggest a possible misspelling correction to the current query.

## Search Control

The [Search Control](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/search-control-fulltextsearchbox) control is responsible for generating the search box. Besides the search filed, the control renders a combo for restricting a search in one department.

## Customizing the search result

You can provide your customers with a more customized experience navigating the search result. You may want to present custom search results for each customer or even engage your users with specific products through a URL.

* [Segmenting the search result](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-segmenting-the-search-result)
* [Building a search results page with multiple layouts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-building-a-search-results-page-with-multiple-layouts)
* [Creating a custom search results page](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-a-custom-search-results-page)

![{"base64":"  ","img":{"width":1022,"height":403,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":2628533,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-segmenting-the-search-result.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-segmenting-the-search-result.gif)

## Integrating an external search provider with VTEX

The [Search Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/search-integration-guide) defines the contract between an external search provider and a VTEX store running on VTEX IO. If a search provider adheres to this protocol, it can completely replace the original VTEX search capabilities without needing to implement any frontend pages or react components.

* [Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-search-provider-overview)
* [Specification](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-search-provider-specification)
* [Recipe](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-search-provider-recipe)
* [Reference Implementations](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-search-provider-reference)

## Integrating your search with Google services

You can integrate your store's search to some Google features, such as the Google Chrome language processing and Google Analytics. These integrations can help retailers analyze user queries, measure the store's main searched terms, and create a more accessible environment for customers.

* [Search Console](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-google-search-console)
* [Setting up Google Analytics search tracking](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-setting-up-google-analytics-search-tracking)
* [Speech to Text Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtexarg-speech-to-text)

## Consulting search information using Legacy Search

Legacy Search allows you to query, search and sort products in the catalog using fulltext, category, and brand search terms.

* [Legacy Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/search-api%23overview)
* [How search parameters work](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/how-search-parameters-work)

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7108339%3Fv%3D4%26w=64%26q=75)](https://github.com/brunoamui)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Getting-Started/search-overview.md)

[Fulfillment« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview//docs/guides/fulfillment)[PricingNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview//docs/guides/pricing-overview)

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7108339%3Fv%3D4%26w=64%26q=75)](https://github.com/brunoamui)

ON THIS PAGE

[Setting up the Intelligent Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23setting-up-the-intelligent-search)

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23search)[Intelligent Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23intelligent-search-api)

[Customizing the search experience of your store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23customizing-the-search-experience-of-your-store)

[Search Result](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23search-result)[Search Bar](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23search-bar)[Autocomplete](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23autocomplete)[Banners](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23banners)[Suggestions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23suggestions)[DidYouMean](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23didyoumean)

[Search Control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23search-control)

[Customizing the search result](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23customizing-the-search-result)

[Integrating an external search provider with VTEX](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23integrating-an-external-search-provider-with-vtex)

[Integrating your search with Google services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23integrating-your-search-with-google-services)

[Consulting search information using Legacy Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23consulting-search-information-using-legacy-search)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Getting-Started/search-overview.md)

Copy page

On this page

ON THIS PAGE

[Setting up the Intelligent Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23setting-up-the-intelligent-search)

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23search)[Intelligent Search API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23intelligent-search-api)

[Customizing the search experience of your store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23customizing-the-search-experience-of-your-store)

[Search Result](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23search-result)[Search Bar](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23search-bar)[Autocomplete](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23autocomplete)[Banners](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23banners)[Suggestions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23suggestions)[DidYouMean](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23didyoumean)

[Search Control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23search-control)

[Customizing the search result](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23customizing-the-search-result)

[Integrating an external search provider with VTEX](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23integrating-an-external-search-provider-with-vtex)

[Integrating your search with Google services](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23integrating-your-search-with-google-services)

[Consulting search information using Legacy Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-overview/docs/guides/search-overview%23consulting-search-information-using-legacy-search)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)