[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 ppp applied to pos 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-ppp-applied-to-pos/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/updates/release-notes)

Guides

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

---

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

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/erp-integration-guide)

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

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

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

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

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

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

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

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

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/payments-integration-payment-provider-framework)

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

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

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

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

[Antifraud Provider Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/payments-integration-pci-dss-compliance)

[Secure Proxy](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/search-integration-guide)

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

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

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

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

---

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

---

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

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/data-protection-plus)

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/erp-integration-guide)

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

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

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

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

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

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

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

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

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/payments-integration-payment-provider-framework)

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

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

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

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

[Antifraud Provider Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/payments-integration-pci-dss-compliance)

[Secure Proxy](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/search-integration-guide)

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

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

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

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

---

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

---

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

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/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-ppp-applied-to-pos/docs/guides/data-protection-plus)

---

Weni by VTEX

---

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

Integration Guides

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

[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-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos)

Payment Provider Protocol for Point of Sale (POS) - VTEX Sales App

VTEX has multiple solutions to deliver a [Unified Commerce](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/unified-commerce-strategies--3WGDRRhc3vf1MJb9zGncnv) experience to shoppers, being able to handle orders from both the ecommerce and physical stores. To deal with the physical store experience, VTEX offers the [VTEX Sales App](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/instore-getting-started-and-setting-up--zav76TFEZlAjnyBVL5tRc), where sellers can serve customers and complete the entire sales process. When finishing a purchase, the customer will have the option to make the payment with a physical card in a payment terminal, also known as a Point of Sale (POS).

For payment partners to integrate their solutions for payments using a POS, there are a series of requirements that must be taken into account. You can check a summary of the requirements in the list below:

* Develop a payment connector using the [Payment Provider Protocol (PPP)](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/payment-provider-protocol--RdsT2spdq80MMwwOeEq0m). There are some details required in the connector to deal with payments on a POS, such as:
   * Include the supported payment methods (credit or debit card) in the [Manifest](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23get-/manifest).
   * Use [callbacks](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/payment-provider-protocol--RdsT2spdq80MMwwOeEq0m%23payment-authorization) for asynchronous payments.
   * Work with [Payment Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app) to identify the POS and wait for its response.
   * The endpoint must return to any call in less than 20 seconds.
* For testing, have a VTEX store configured with the supported payment methods. This should be provided by VTEX.
* If needed for testing, have a device with the [VTEX Sales App installed](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/instore-using-the-app--4BYzQIwyOHvnmnCYQgLzdr/2rPSJ8519UCCZo5uEBkqxh).
* Developers might want to create their Payment App to identify the POS. This app will also have to be installed in the store.

> To develop a new payment connector, it is mandatory to follow the **prerequisites determined by VTEX**. You can learn about them in the [Implementation prerequisites section of our Payment Provider Protocol article](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/payment-provider-protocol--RdsT2spdq80MMwwOeEq0m%23implementation-prerequisites).

## Payment connector pre-requisites

There are some steps needed for the connector to be able to process payments in the physical world, which are described below:

1. Route [GET List Payment Provider Manifest](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23get-/manifest) (`/manifest`). The response body of the endpoint must contain the payment methods `Venda Direta Credito` and `Venda Direta Debito`. In case a split of receivables is offered, this must be informed in the `allowsSplit` field for each payment method. Example of response body properly configured:

`1

{

2

 paymentMethods:

3

 [

4

 {

5

 name: "American Express",

6

 allowsSplit: "onCapture"

7

 },

8

 {

9

 name: "Diners",

10

 allowsSplit: "onCapture"

11

 },

12

 {

13

 name: "Elo",

14

 allowsSplit: "onCapture"

15

 },

16

 {

17

 name: "Hipercard",

18

 allowsSplit: "onCapture"

19

 },

20

 {

21

 name: "Mastercard",

22

 allowsSplit: "onCapture"

23

 },

24

 {

25

 name: "Visa",

26

 allowsSplit: "onCapture"

27

 },

28

 {

29

 name: "Boleto Bancário",

30

 allowsSplit: "onAuthorize"

31

 },

32

 {

33

 name: "Visa Electron",

34

 allowsSplit: "disabled"

35

 },

36

 {

37

 name: "Maestro",

38

 allowsSplit: "disabled"

39

 },

40

 {

41

 name: "Pix",

42

 allowsSplit: "onAuthorize"

43

 },

44

+ {

45

+ name: "Venda Direta Debito",

46

+ allowsSplit: "onCapture"

47

+ },

48

+ {

49

+ name: "Venda Direta Credito",

50

+ allowsSplit: "onCapture"

51

+ }

52

 ]

53

}

`

1. Route [POST Create Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments) (`/payments`). This route must be idempotent, which means that the provider must be able to correctly handle if the route is called many times with the same `paymentId`. The provider should not recreate the payment for multiple calls but has to return the most updated status instead.

## Scenery and flow

Here we describe the payment flow in the context of a physical store using a POS. The following sequence diagram represents all the steps in this flow, where the green bars are the steps that the payment provider is responsible for:

![{"base64":"  ","img":{"width":2502,"height":1638,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":339570,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-ppp-applied-to-pos-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-ppp-applied-to-pos-0.png)

1. The flow starts with a buyer finishing a purchase in a VTEX physical store created on [VTEX Sales App](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/instore-getting-started-and-setting-up--zav76TFEZlAjnyBVL5tRc).
2. The VTEX Sales App makes an [Authorization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payments-gateway-api%23post-/api/pvt/transactions/-transactionId-/authorization-request) request to the VTEX Payment Gateway.
3. Our Gateway makes a [Create Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments) request to the connector defined in the store settings for the specific payment method used in the purchase (i.e.: `Venda Direta Credito`).
4. The Gateway receives the Create Payment response from the connector with the `undefined` status and the `appname` field of the `paymentAppData` parameter filled with the name of an app (i.e.: `vtex.challenge-terminal-connector-app`). It means that the payment is not concluded and it needs to do a challenge by opening a [Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app%23understanding-the-payment-app-flow), which will be responsible to identify the POS.
5. The VTEX Sales App receives the response from the Gateway and opens the app to start the challenge.
6. The seller interacts with the app to identify the POS to be used in the payment process. Then the app sends the serial number of the POS to the connector and closes.
7. The connector requests to update the order in the payment processor with the serial number of the POS.
8. After the app closes, a callback is triggered in the VTEX Sales App to the Gateway, initiating the sequence of requests to make the payment in the POS.
   1. The Gateway makes a Create Payment request to the connector with the same payment ID used in step 3\. This means that the Gateway is waiting for an update on the payment status.
   2. The connector calls the payment processor to start the payment in the POS.
   3. The payment processor calls the POS to make the payment with the card. Then, the payment processor returns to the connector telling that the payment in the POS has started.
   4. Since it takes some time for the payment to be concluded in the POS, the connector returns to the Gateway once more with an `undefined` status and information to open another Payment App called `vtex.challenge-wait-for-confirmation`.
   5. The Gateway returns to the VTEX Sales App telling it to open the [Wait for confirmation app](#wait-for-confirmation).
9. The VTEX Sales App opens the [Wait for confirmation app](#wait-for-confirmation), so the user visually understands that the VTEX Sales App is waiting for the POS to finish the payment.
   1. The [Wait for confirmation app](#wait-for-confirmation) asks the Gateway for the updated payment status.
   2. The Gateway uses the Create Payment request to the connector for the updated payment status.
   3. While the POS does not finish the payment and responds, the Payment Connector keeps responding that the payment status is `undefined`.
   4. The Gateway responds to the [Wait for confirmation app](#wait-for-confirmation) app with the `undefined` status.
   5. The [Wait for confirmation app](#wait-for-confirmation) enters in a loop, repeating from step 9.1., calling the Gateway again for the updated status until the POS finishes the payment and the status change or there is a timeout. The time for the timeout is defined in the `secondsWaiting` parameter from the payload. If there is a timeout, the payment is canceled and the buyer has to finish the order again. More information can be found in the [Wait for confirmation app](#wait-for-confirmation) subsection in this article.
10. After step 8.3., many of the steps occurred in the background. But from that point, the buyer is allowed to insert the card and interact with the POS to perform the payment.
11. The POS responds to the payment processor from the request in step 8.3.
12. The payment processor processes the transaction and uses a webhook to call the connector.
13. The payment provider makes a mandatory [callback](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/payment-provider-protocol--RdsT2spdq80MMwwOeEq0m%23payment-authorization) request to the Gateway (without which it is not possible to approve or deny the POS transaction), sending the following information to VTEX:
   * Payload containing card information (`cardBrand`, `firstDigits` and `lastDigits` fields)
   * Payment status (`approved` or `denied`)
14. The [Wait for confirmation app](#wait-for-confirmation) requests the Gateway once more for the updated payment status.
15. The [Wait for confirmation app](#wait-for-confirmation) receives the updated payment status.
16. The [Wait for confirmation app](#wait-for-confirmation) responds to the VTEX Sales App that it can proceed, so the app is closed.
17. From a callback, the VTEX Sales App calls the Gateway to know the status of the payment.
18. The Gateway responds to the VTEX Sales App with the last status. If the payment status is `denied` or `canceled`, the VTEX Sales App shows an error and the buyer can try to finish the purchase again from the checkout. Else, the purchase is concluded and the order is placed in the system.

### Details on the Create Payment route

The request body of the [Create Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments) endpoint has many parameters. Some of them require more attention in the context of physical stores and are detailed below:

* `card`: VTEX’s Gateway does not receive card data for payments in physical stores. Therefore, this object is sent with all its fields as `null`.

`1

"card": {

2

 "holder": null,

3

 "number": null,

4

 "csc": null,

5

 "expiration": {

6

 "month": null,

7

 "year": null

8

 },

9

 "document": null,

10

 "token": null

11

 }

`

* `paymentMethod`: for payments in physical stores, instead of using values like `"Visa"` and `"Mastercard"`, this field will be filled with the values `"Venda Direta Debito"` or `"Venda Direta Credito"`. If the connector works both for ecommerce and physical payments, it can decide which of them is being used by checking this field.
* `callbackUrl`: this field is needed since physical payments follow an asynchronous flow. The Gateway uses this field to tell the provider which URL has to be used to notify VTEX about updates in the payment status. First, the payment is created with an `undefined` status. Then, when the status changes to `approved` or `denied`, the provider has to send a request to the URL from the `callbackUrl` field with the updated status. You can find more details about this flow in the [Additional interactions and paymentAppData](#additional-interactions-and-paymentappdata) section and the [Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app%23understanding-the-payment-app-flow) article.

### Asynchronous flow and delayToCancel

When VTEX Payment Gateway calls the Create Payment endpoint, the connector starts an asynchronous authorization process, which returns immediately with an `undefined` status. This flow is similar to other asynchronous payment methods like Pix and Boleto (common methods used in Brazil). After the Gateway receives the initial status as `undefined`, at some point the payment will be concluded and the status will be updated to `approved` or `denied`.

It is important to note that the payment cannot stay `undefined` forever. There is a limit of time that VTEX’s Gateway waits for the conclusion of the payment. If this time limit is exceeded, the Gateway automatically calls the [Cancel Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments/-paymentId-/cancellations) endpoint of the connector. This time limit is defined by the connector and informed by the `delayToCancel` field in the response body of the Create Payment route, expressed in seconds.

### Additional interactions and paymentAppData

At VTEX, payments in physical stores follow an asynchronous flow that requires additional interactions with the user, also called challenges, until it is approved. To offer this kind of interaction, the connector has to tell our Gateway from the `paymentAppData` field in the response of the Create Payment endpoint. This field contains the name of the VTEX IO app (`appName`) that will be presented on the VTEX Sales App and the data needed for the app to work (`payload`).

We have some apps that are ready to use for additional interaction with payments on a POS.

> Besides the provided apps, partners can also develop apps for their specific needs. You can check more details in the [Payment App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-app) article.

#### Terminal connector App

This app uses the device camera to read the barcode of the POS that will be used for the purchase. After reading the barcode, the information is sent automatically to the URL defined by the `submitUrl` parameter. The payload sent by the app to the URL uses the following format: `{"serialNumber": "12345"}`.

Fields used in this app:

* `appName`:
   * `vtex.terminal-connector-app`
* `payload`:
   * `submitUrl` (string): URL where the `serialNumber` is sent to.

Payload example:

`1

"paymentAppData": {

2

 "appName": "vtex.terminal-connector-app",

3

 "payload":

4

 "{

5

 \"submitUrl\": \"https://coolacquirer.com/instore_config/1231231\"

6

 }"

7

}

`

![{"base64":"  ","img":{"width":846,"height":1006,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":359184,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-ppp-applied-to-pos-2.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-ppp-applied-to-pos-2.png)

#### Wait for confirmation

This app is returned by the connector after the payment has started on the POS, so that the VTEX Sales App polls for the payment status. The waiting time for a status change in the payment is defined by the `secondsWaiting` parameter, which comes from the connector in the payload.

Fields used in this app:

* `appName`:
   * `vtex.challenge-wait-for-confirmation`
* `payload`:
   * `secondsWaiting` (int): defines how many seconds the app will keep open waiting for a payment status update.

Payload example:

`1

"paymentAppData": {

2

 "appName": "vtex.challenge-wait-for-confirmation",

3

 "payload": "{ \"secondsWaiting\": 600 }"

4

}

`

### Interaction with the POS

After the user interacts with the app that identifies the POS, the payment processor is responsible for the communication with the POS to read the physical card of the buyer. When communicating with the POS, the payment process is done without VTEX’s intervention. The payment processor is also responsible to deal with retries caused by password errors, insufficient credit, and other reasons.

When the payment processor receives an answer that the payment is either approved or denied, it has to tell VTEX Payment Gateway the response with the payment status. This is done through the callback flow using the URL in the `callbackUrl` field from the Create Payment request. You can find more details about this flow in the [Payment Authorization section of the Payment Provider Protocol](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/payment-provider-protocol--RdsT2spdq80MMwwOeEq0m%23payment-authorization) article.

The callback flow starts with the payment connector calling the URL in the `callbackUrl` field to the Gateway. The callback request can be one of two types: retry or notification. If it is a retry, the `/retry` route will be used and the Gateway will make another Create Payment request to receive the updated status. If it is a notification, the connector calls the `/notification` endpoint to tell the Gateway about the updated status. For physical payments, the payload of the callback request must have three additional fields about the card used in the payment, which are used for conciliations and merchant’s financial reports:

* `cardBrand`: Brand of the card.
* `firstDigits`: First six digits of the card number.
* `lastDigits`: Last four digits of the card number.

## Testing your connector

Before a VTEX store can provide payments in the physical world, some setup steps are needed in the payments Gateway. VTEX provides a store to the payment provider for testing during the development process, which will be already configured and ready to use. Nevertheless, you can follow the steps below to configure a store whenever needed:

1. Install the connector you developed in the store. If you are creating a PPF connector using VTEX IO, check the steps in the [Payment Provider Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-provider-framework%23placing-an-order-with-your-new-connector) article to properly install this type of connector. If you need help with the installation, you can [open a ticket to VTEX support team](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/opening-tickets-to-vtex-support--16yOEqpO32UQYygSmMSSAM?locale=en).
2. Configure a Gateway affiliation with the installed connector. You can find more details in the [Registering gateway affiliations](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/registering-gateway-affiliations--tutorials%5F444) article.
3. Configure a payment condition that works with a POS. For credit cards is **Venda Direta Crédito**, and for debit cards is **Venda Direta Débito**. Remember to choose the configured affiliation. You can find more details in the [Configuring payment conditions](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/how-to-configure-payment-conditions--tutorials%5F455) article.
4. Make the payment method available on the VTEX Sales App by following the steps in the [Define payment methods displayed on VTEX Sales App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/define-payment-methods-displayed-on-vtex-sales-app) article. The ID of the payment conditions used in the `filter` array is `44` for debit and `45` for credit and it can also be checked on the **Payment Conditions** page of the Admin.
5. [Install the VTEX Sales App](https://read.calvincode.net/reader?url=https://help.vtex.com/pt/tracks/instore-using-the-app--4BYzQIwyOHvnmnCYQgLzdr/2rPSJ8519UCCZo5uEBkqxh) on a device of your choice.
6. Simulate a purchase using your connector as a payment condition.

## Making your connector available to everyone

When you decide the connector is ready to be available for every VTEX store, you can start the homologation process. You will have to test the endpoints of your connector with the [Payment Provider Test Suite](https://read.calvincode.net/reader?url=https://apps.vtex.com/vtex-payment-provider-test-suite/p) app and, if all the tests pass, you will have to [open a ticket to VTEX support team](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/opening-tickets-to-vtex-support--16yOEqpO32UQYygSmMSSAM?locale=en) to publish your connector. You can find more details about the homologation process in the [Payment Provider Protocol](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/payment-provider-protocol--RdsT2spdq80MMwwOeEq0m%233-payment-provider-homologation) and the [Payment Provider Homologation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-payment-provider-homologation) articles.

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/_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-ppp-applied-to-pos/_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-ppp-applied-to-pos/_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-ppp-applied-to-pos.md)

[Payment Provider Protocol« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos//docs/guides/payments-integration-payment-provider-protocol)[Implementing a Payment ProviderNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos//docs/guides/payments-integration-implementing-a-payment-provider)

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/_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-ppp-applied-to-pos/_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-ppp-applied-to-pos/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7108339%3Fv%3D4%26w=64%26q=75)](https://github.com/brunoamui)

ON THIS PAGE

[Payment connector pre-requisites](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23payment-connector-pre-requisites)

[Scenery and flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23scenery-and-flow)

[Details on the Create Payment route](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23details-on-the-create-payment-route)[Asynchronous flow and delayToCancel](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23asynchronous-flow-and-delaytocancel)[Additional interactions and paymentAppData](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23additional-interactions-and-paymentappdata)[Interaction with the POS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23interaction-with-the-pos)

[Testing your connector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23testing-your-connector)

[Making your connector available to everyone](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23making-your-connector-available-to-everyone)

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-ppp-applied-to-pos.md)

Copy page

On this page

ON THIS PAGE

[Payment connector pre-requisites](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23payment-connector-pre-requisites)

[Scenery and flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23scenery-and-flow)

[Details on the Create Payment route](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23details-on-the-create-payment-route)[Asynchronous flow and delayToCancel](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23asynchronous-flow-and-delaytocancel)[Additional interactions and paymentAppData](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23additional-interactions-and-paymentappdata)[Interaction with the POS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23interaction-with-the-pos)

[Testing your connector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23testing-your-connector)

[Making your connector available to everyone](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-ppp-applied-to-pos/docs/guides/payments-integration-ppp-applied-to-pos%23making-your-connector-available-to-everyone)

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 assembly options 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/assembly-options-app/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-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/assembly-options-app/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-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/assembly-options-app/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-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/assembly-options-app/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/advanced-components)

---

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

---

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

---

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

[AB Tester](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtexarg.abtester)

[Abandoned Cart Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.abandoned-cart-service)

[Badges](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.badges)

[Broadcaster](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.broadcaster)

[Catalog Images](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.catalog-images)

[Checkout UI Custom](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.checkout-ui-custom)

[Checkout UI Settings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.checkout-ui-settings)

[Messages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.messages)

[Product Context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.product-context)

[Pickup point selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtexbr.pickup-selector)

[Rewriter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.rewriter)

[Responsive Values](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.responsive-values)

[Search GraphQL](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.search-graphql)

[Session Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.session-client)

[Store Icons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.store-icons)

[Store Sitemap](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.store-sitemap)

[VTEX Telemarketing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.telemarketing)

[Assembly Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/assembly-options-app)

[Affiliates Program](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/affiliates-program-app)

---

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

---

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

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.my-account)

---

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

---

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

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

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

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

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

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

---

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

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/advanced-components)

---

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

---

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

---

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

[AB Tester](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtexarg.abtester)

[Abandoned Cart Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.abandoned-cart-service)

[Badges](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.badges)

[Broadcaster](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.broadcaster)

[Catalog Images](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.catalog-images)

[Checkout UI Custom](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.checkout-ui-custom)

[Checkout UI Settings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.checkout-ui-settings)

[Messages](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.messages)

[Product Context](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.product-context)

[Pickup point selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtexbr.pickup-selector)

[Rewriter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.rewriter)

[Responsive Values](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.responsive-values)

[Search GraphQL](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.search-graphql)

[Session Client](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.session-client)

[Store Icons](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.store-icons)

[Store Sitemap](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.store-sitemap)

[VTEX Telemarketing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.telemarketing)

[Assembly Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/assembly-options-app)

[Affiliates Program](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/affiliates-program-app)

---

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

---

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

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/apps/vtex.my-account)

---

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

---

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

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

[Assembly Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/guides/assembly-options-app)

Assembly Options

> This app is available only for stores developed in [VTEX IO](https://read.calvincode.net/reader?url=https://vtex.com/br-pt/store-framework/).

At VTEX, [Assembly Options](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/assembly-options--5x5FhNr4f5RUGDEGWzV1nH) consist on creating [attachments](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/what-is-an-attachment--aGICk0RVbqKg6GYmQcWUm) for complex scenarios, where it is necessary to offer various combinations of SKUs, quantities, additional items and costs.

The **Assembly Options** app provides an interface on VTEX Admin to create and manage product customization options available to customers in a specific store. This experience aims to offer a simple and easy-to-use alternative to the [manual configuration](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/assembly-options--5x5FhNr4f5RUGDEGWzV1nH%23attachments) available through **Catalog > Attachments** using a certain attachment syntax.

## Before you begin

To use Assembly Options, you must first install and configure [Product Customizer](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-product-customizer) in your store.

We also recommend reading our [Assembly Options](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/assembly-options--5x5FhNr4f5RUGDEGWzV1nH) documentation for more information on this feature.

## Installation

> When this app is installed in a [seller account](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/what-is-a-seller--5FkLvhZ3Few4CWWIuYOK2w), the Assembly Option is displayed at checkout. To display it on the product page, you must install the app in a [marketplace account](https://read.calvincode.net/reader?url=https://help.vtex.com/tutorial/what-is-a-marketplace--680lLJTnmEAmekcC0MIea8%23).

You can install the app for free in the [VTEX App Store](https://read.calvincode.net/reader?url=https://apps.vtex.com/vtex-admin-assembly-options/p) or using 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), by running `vtex install vtex.admin-assembly-options@2.x` in your terminal.

After the installation, you can find the app's interface on VTEX Admin, by accessing _Products > Assembly options_ or by going directly to the URL `{accountName}.myvtex.com/admin/assembly-options/`, replacing `{accountName}` with your VTEX account.

This app installs Assembly Options GraphQL as a dependency. Learn more about it by accessing the [assembly-options-graphql](https://read.calvincode.net/reader?url=https://github.com/vtex/assembly-options-graphql) repository.

## How the app works

The app inserts a new menu in the VTEX Admin, which you can access on _Products > Assembly options_.

![{"base64":"  ","img":{"width":1905,"height":565,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":51509,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-0.png)

The Assembly Options interface allows you to:

View a list of existing Assembly Options.

![{"base64":"  ","img":{"width":3578,"height":1704,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":7200147,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-1.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-1.gif)

Search for Assembly Options.

![{"base64":"  ","img":{"width":3578,"height":1704,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":5795882,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-2.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-2.gif)

Filter Assembly Options by Status.

![{"base64":"  ","img":{"width":3578,"height":1704,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":5019831,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-3.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-3.gif)

Create Assembly Options.

![{"base64":"  ","img":{"width":3578,"height":1704,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":6253689,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-4.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-4.gif)

Edit Assembly Options.

![{"base64":"  ","img":{"width":3578,"height":1704,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":7061610,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-5.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-5.gif)

Delete Assembly Options.

![{"base64":"  ","img":{"width":3578,"height":1704,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":6424390,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-6.gif"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/assembly-options-app-6.gif)

For more information on how to use this interface, read our user guide [Assembly Options app](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/assembly-options-app--54mWg37mojrqOgCA79iqqk).

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/_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/Store-Framework-Apps/functional-apps/assembly-options-app.md)

[VTEX Telemarketing« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app//docs/apps/vtex.telemarketing)[Affiliates ProgramNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app//docs/guides/affiliates-program-app)

Contributors

1

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

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/assembly-options-app%23before-you-begin)

[Installation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/assembly-options-app%23installation)

[How the app works](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/assembly-options-app%23how-the-app-works)

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/Store-Framework-Apps/functional-apps/assembly-options-app.md)

Copy page

On this page

ON THIS PAGE

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/assembly-options-app%23before-you-begin)

[Installation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/assembly-options-app%23installation)

[How the app works](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/assembly-options-app/docs/guides/assembly-options-app%23how-the-app-works)

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 shelf template controls 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/shelf-template-controls/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/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/shelf-template-controls/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/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/shelf-template-controls/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/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/shelf-template-controls/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/store-framework)

---

(Legacy) CMS Portal

[Migrating your storefront from Legacy CMS Portal to Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/vtex-io-documentation-migrating-storefront-from-legacy-to-io)

[Can I order my product as I want?](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/can-i-order-my-product-as-i-want)

[List of controls for templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/list-of-controls-for-templates)

[Setting up the zoom](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/setting-up-the-zoom)

[Creating gift lists](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/creating-gift-lists)

[Validating a layout before moving it to production](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/validating-a-layout-before-moving-it-to-production)

[How to use the page title control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/how-to-use-the-page-title-control)

[How product name control works](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/how-product-name-control-works)

[Configure the price history control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/configure-the-price-history-control)

[Shelf template controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls)

[Control to disable the canonical tag](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/control-to-disable-the-canonical-tag)

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/storefront-best-practices)

---

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

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

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

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

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

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

---

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

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/faststore)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/store-framework)

---

(Legacy) CMS Portal

[Migrating your storefront from Legacy CMS Portal to Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/vtex-io-documentation-migrating-storefront-from-legacy-to-io)

[Can I order my product as I want?](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/can-i-order-my-product-as-i-want)

[List of controls for templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/list-of-controls-for-templates)

[Setting up the zoom](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/setting-up-the-zoom)

[Creating gift lists](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/creating-gift-lists)

[Validating a layout before moving it to production](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/validating-a-layout-before-moving-it-to-production)

[How to use the page title control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/how-to-use-the-page-title-control)

[How product name control works](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/how-product-name-control-works)

[Configure the price history control](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/configure-the-price-history-control)

[Shelf template controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls)

[Control to disable the canonical tag](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/control-to-disable-the-canonical-tag)

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/storefront-best-practices)

---

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

(Legacy) CMS Portal

[Shelf template controls](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls)

Shelf template controls

Get to know Legacy CMS controls for creating product shelves.

The Legacy CMS Portal provides a range of controls for creating product shelves. Below, you'll find the most commonly used variables and properties for defining product shelves, including examples for reference.

## Declaring product variables

Product attributes can be stored in variables, and these are used in every template. To declare the variables and receive an attribute of a product, use the following command:

`1

#set ($variable=$attribute)

`

### Examples

* `#set($id = $product.Id)`
* `#set($uri = $product.Uri)`
* `#set($escapedName = $product.HtmlEscapedName)`
* `#set($evaluationRate = $product.EvaluationRate)`

## Product and SKU

| Property                                                | Description                                                                                |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| $product.Id                                             | Shows the product ID.                                                                                |
| $product.EscapedName                                    | Shows the product name.                                                                                |
| $product.DescriptionShort                               | Shows a brief product description.                                                                                |
| $product.Uri                                            | Shows the product link.                                                                                |
| $product.GetImageTag(number corresponding to the image) | Shows the image and the type of image you want. It follows this list of image types: ProductImageShowcaseLittle (Size: 65×65) = 1;ProductImageShowcaseMedium (Size: 90×90) = 29;ProductImageShowcaseLarge (Size: 130×130) = 30;MainProductImage (Size: 250×250) = 2;ThumbProductImage (Size: 45×45) = 3;ZoomProductImage (Size: 344×344) = 10;File = 11;ProductManual = 12; The sizes of the images are according to the store's layout. |
| $product.ProductField(IdField)                          | Shows the value of a product field by passing the ID of this field as a parameter.                                                                                |

## Price

| Property                                  | Description                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| $product.ListPrice                        | Shows the "From" price of the product.                                                                                |
| $product.BestPrice                        | Shows the best price of the product.                                                                                |
| $product.HasBestPrice                     | Indicates whether there is a better price for the product (used in conditionals).                                                                                |
| $product.NumbersOfInstallment             | Shows the number of installments of the best payment condition for the product.                                                                                |
| $product.InstallmentValue                 | Shows the value of the installment of the best payment condition for the product, i.e., the value of the largest interest-free installment.                                                                                |
| $product.MaxNumbersOfInstallment          | Shows the largest installment with or without interest for this product.                                                                                |
| $product.MaxInstallmentValue              | Shows the value of the installment of the product's highest payment condition, i.e., the value of the largest installment with or without interest.                                                                                |
| $product.BestPricePlusTax                 | Shows the price PLUS the rates applied to it. Rate values that are set by region, i.e., by using zip codes, will not be displayed on the shelves. If more than one rate includes the same product, the values are summed and displayed by the control. |
| $product.ListPriceMinusBestPrice          | Shows the absolute difference between the "From" price and the best price of the product.                                                                                |
| $product.ListPriceMinusBestPriceInPercent | Shows the difference (in percentage) of the price "From" to the best price.                                                                                |

## Departament and Category

| Property                | Description                                    |
| ----------------------- | ---------------------------------------------- |
| $product.DepartmentName | Displays the name of the product's department. |
| $product.DepartmentLink | Displays the link of the product's department. |
| $product.CategoryName   | Displays the name of the product's category.   |
| $product.CategoryLink   | Displays the link of the product's category.   |

## Brand

| Property           | Description                                          |
| ------------------ | ---------------------------------------------------- |
| $product.BrandName | Shows the name of the product's brand.               |
| $product.Brand     | Shows the product's brand in a link-friendly format. |
| $product.BrandLink | Shows the link to the brand.                         |

## Buy button

| Property                            | Description                                                                                |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| $product.BottomBuyAllSku            | Includes a buy button to add to the shelf list, where the product with specifications added by the customer is sent directly to the cart. If the product has already been purchased for the list, a specific class is added to the item for customization. The control must be added to the shelf template used in the “Lista-Prateleira” page template. |
| $product.BottomBuy                  | Includes a buy button in the shop window that takes the customer directly to the cart if there is only 1 SKU.                                                                                |
| $product.ButtonBuyModal(false,true) | Includes a buy button that inserts the product into the cart and keeps the customer in the shop window. This control needs the $product.AmountInCart control to add a desired quantity textbox for adding to the cart.                                                                                |
| $product.AmountInCart               | Inserts a textbox element to set the desired quantity of the product to be added to the cart. This control is used in conjunction with the control $product.ButtonBuyModal(false,true).                                                                                |

## Others

| Property                        | Description                                                                                |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| $product.EvaluationRate         | Shows the product rating.                                                                                |
| $product.HightLight             | Shows the collections of highlights of which the product is part.                                                                                |
| $product.DiscountHightLight     | Shows the promotions with highlights of which the product is part. If the promotion has any condition of freight, payment method, or cluster, it will not be presented until these conditions are met.                                                                                |
| $product.IsInStock              | Indicates whether the product has items in stock (used in conditionals).                                                                                |
| $product.Tax                    | Shows the rates registered for the product.                                                                                |
| $product.QuickView              | Shows the Quick View button.                                                                                |
| $product.Compare                | Shows the checkbox to select the products to be compared.                                                                                |
| $product.BestRewardValue        | Displays the value for the "Fidelity Value" field of the SKU form.                                                                                |
| $product.PercentBougthAndBought | Shows the percentage value on shelves of type "Who bought also bought."                                                                                |
| $product.PercentBoughtAlso      | Shows the percentage value on shelves of type "Who saw also bought."                                                                                |
| $product.PercentViewedAlso      | Shows the percentage value on shelves of type "Who saw also saw."                                                                                |
| $product.InsertSku              | Shows the individual number of products in the shop window and a checkbox for each product SKU, allowing you to select which SKUs will be added to the list. To add more than one SKU, it is necessary to change the quantity inside the box and then select the checkbox for the SKU. If the quantity is changed and the checkbox of an SKU is selected, the quantity of this SKU will not change; only the next SKUs will be selected after changing the quantity in the box. |

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/_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/shelf-template-controls/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F83723439%3Fv%3D4%26w=64%26q=75)](https://github.com/jumeyermattosarruda)

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/legacy-cms/shelf-template-controls.md)

[Configure the price history control« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls//docs/guides/configure-the-price-history-control)[Control to disable the canonical tagNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls//docs/guides/control-to-disable-the-canonical-tag)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/_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/shelf-template-controls/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F83723439%3Fv%3D4%26w=64%26q=75)](https://github.com/jumeyermattosarruda)

ON THIS PAGE

[Declaring product variables](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23declaring-product-variables)

[Examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23examples)

[Product and SKU](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23product-and-sku)

[Price](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23price)

[Departament and Category](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23departament-and-category)

[Brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23brand)

[Buy button](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23buy-button)

[Others](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23others)

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/legacy-cms/shelf-template-controls.md)

Copy page

On this page

ON THIS PAGE

[Declaring product variables](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23declaring-product-variables)

[Examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23examples)

[Product and SKU](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23product-and-sku)

[Price](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23price)

[Departament and Category](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23departament-and-category)

[Brand](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23brand)

[Buy button](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23buy-button)

[Others](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/shelf-template-controls/docs/guides/shelf-template-controls%23others)

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=)