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

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

[Assistant]
Documentation

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

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

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

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

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

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

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

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

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-getting-started)

---

Project structure

[Manifest](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-manifest)

[Billing Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-billing-options)

[Builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-builders)

[Admin Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-admin-builder)

[Assets Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-assets-builder)

[Docs Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-docs-builder)

[GraphQL Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-graphql-builder)

[Messages Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-messages-builder)

[Node Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-node-builder)

[PaymentProvider Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-paymentprovider-builder)

[Pixel Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-pixel-builder)

[React Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-react-builder)

[Store Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-store-builder)

[Styles Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-styles-builder)

[Dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-dependencies)

[Peer Dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-peerdependencies)

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

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

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

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

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

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

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

---

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

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-getting-started)

---

Project structure

[Manifest](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-manifest)

[Billing Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-billing-options)

[Builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-builders)

[Admin Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-admin-builder)

[Assets Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-assets-builder)

[Docs Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-docs-builder)

[GraphQL Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-graphql-builder)

[Messages Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-messages-builder)

[Node Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-node-builder)

[PaymentProvider Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-paymentprovider-builder)

[Pixel Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-pixel-builder)

[React Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-react-builder)

[Store Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-store-builder)

[Styles Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-styles-builder)

[Dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-dependencies)

[Peer Dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-peerdependencies)

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

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

Project structure

[Builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-builders)

[React Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-react-builder)

React builder

Learn how to use the VTEX IO React builder.

The `react` builder is used to develop apps with [React](https://read.calvincode.net/reader?url=https://react.dev/) when your project requires customized frontend solutions not covered by our native components.

This builder interprets the `/react` directory, where you must place the app’s React code using [Typescript](https://read.calvincode.net/reader?url=https://www.typescriptlang.org/). When you run your app, this code is transformed into compiled bundles, ready for use in frontend apps.

To learn how to implement apps using this builder, check our [Storefront apps guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-1-developing-storefront-apps-using-react-and-vtex-io).

## Folder structure

An app that uses the `react` builder has a folder named `/react` in its root directory. The directory structure may vary depending on the development preferences or specific project settings.

The basic structure of a React folder is composed of the following files, as you can see in the [React boilerplate app](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/react-app-template/tree/master/react):

`1

react

2

 ┣ 📂 typings

3

 ┣ 📄 {ReactCodeFileName}.tsx

4

 ┣ 📄 package.json

5

 ┣ 📄 tsconfig.json

6

 ┗ 📄 yarn.lock

`

* `typings`: Folder holding TypeScript type definitions.
* `.tsx` files: Contain the source code of React components. Replace `{ReactCodeFileName}` according to your scenario.
* `tsconfig.json`: Specifies how the TypeScript compiler should behave, indicating the root directory and the output directory for the compiled code, among other project settings for TypeScript. Check the [tsconfig.json documentation](https://read.calvincode.net/reader?url=https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) to learn more about this file.
* `package.json`: Defines the project’s metadata, dependencies, and custom scripts using [Yarn](https://read.calvincode.net/reader?url=https://yarnpkg.com/migration/overview), and other configuration settings.
* `yarn.lock`: Locks down the exact versions of your project’s dependencies, including transitive dependencies, to ensure consistent builds across different machines and environments. This file is automatically generated based on the dependencies in your `package.json` file.

## Usage

To use the `react` builder, follow these steps:

1. Clone the React [boilerplate app](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/react-app-template/tree/master/react) to your local files.
2. Modify the `manifest.json` file in the React example app to include your app’s metadata, such as its name, version, vendor, and dependencies. The `react` builder must also be declared in the app’s `manifest.json` file as follows:
`1
"builders": {
2
 "react": "3.x"
3
}
`
3. [Link your app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-linking-an-app) to a development workspace.

For more information on how to create a React app using VTEX IO, see [Creating a new app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-3-creating-the-new-app).

> Learn how to link a React component to a Store Framework block in [store builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder).

## Use case examples

The `react` builder is versatile and enables the development of frontend apps with different characteristics and objectives. The [default template](#understanding-the-apps-file-structure) provides only the essential files, but the possibilities are countless.

Below is an example of a React component and its folders and files within the `react` directory.

The [VTEX Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.store-components) is a collection of components that can be used to create or extend other VTEX apps.

> Note that an app using the `react` builder can export a single or multiple components.

This collection is composed by some components, such as [Availability Subscriber](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/docs/vtex-store-components-availabilitysubscriber), [Buy Button](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/docs/vtex-store-components-buybutton), [SKU Selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/docs/vtex-store-components-skuselector), [Search Bar](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/docs/vtex-store-components-searchbar), among others.

The app’s file structure includes folders and files that enable the use of the collection’s React components. You can check some of them below:

`1

react

2

 ┣ 📂 components

3

 ┣ 📂 graphql

4

 ┣ 📂 typings

5

 ┣ 📂 utils

6

 ┣ 📄 {FileName}.tsx

7

 ┣ 📄 {FileName}.tsx

8

 ┣ 📄 {FileName}.js

9

 ┣ 📄 {FileName}.js

10

 ┣ 📄 …

11

 ┣ 📄 package.json

12

 ┣ 📄 tsconfig.json

13

 ┗ 📄 yarn.lock

`

* The `components` folder contains the folders of each React component.
* The `graphql` folder contains GraphQL queries and mutations, which some components use to communicate with the backend. Keeping GraphQL code separate from other parts of the React component promotes modularity and facilitates the management of queries, mutations, or subscriptions specific to the React component.
* The `utils` folder contains utility functions or helper modules used by some components.

Contributors

1

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

Was this helpful?

Yes

No

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

[Pixel Builder« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder//docs/guides/vtex-io-documentation-pixel-builder)[Store BuilderNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder//docs/guides/vtex-io-documentation-store-builder)

Contributors

1

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

ON THIS PAGE

[Folder structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-react-builder%23folder-structure)

[Usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-react-builder%23usage)

[Use case examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-react-builder%23use-case-examples)

Was this helpful?

 Send feedback

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

Copy page

On this page

ON THIS PAGE

[Folder structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-react-builder%23folder-structure)

[Usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-react-builder%23usage)

[Use case examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-react-builder/docs/guides/vtex-io-documentation-react-builder%23use-case-examples)

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 payments integration purchase flows 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-purchase-flows/docs/guides)

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

Guides

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

---

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

---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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

---

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

---

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

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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

---

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

---

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

---

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

---

Weni by VTEX

---

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

Integration Guides

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

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

Purchase Flows

A purchase flow (also known as shopping flow) represents the steps or actions a customer takes in order to complete payment for a purchase. In VTEX, the available purchase flows are:

* Transparent
* Redirect
* Payment App

## Transparent

The Transparent purchase flow is used when customers fill in payment information in the standard SmartCheckout template and complete the purchase without leaving the store. This is the most common option if you want to provide a seamless payment experience.

## Redirect

The Redirect purchase flow is used when customers confirm the payment option in the store and are then redirected to a different page to fill in payment information and complete the purchase.

This option is used when the partner needs a specific interaction with the customer that is not provided by the standard SmartCheckout template.

Some examples include: displaying a QR code for payment, filling in an application form, logging in to an external website.

> For the connector that will use Redirect, there is no need to pass all the Test Suit tests, only the Redirect one.

![{"base64":"  ","img":{"width":1830,"height":1144,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":106531,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-purchase-flows-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-purchase-flows-0.png)

The sequence of events in a Redirect payment flow occurs as described in the following steps:
1. The customer clicks on **Finish Payment** in the Checkout.
2. Checkout calls the Gateway with a [Start Transaction request](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/1createanewtransaction).
3. Gateway calls the provider with an [Authorization request](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/4doauthorization) (POST `/payments`).
4. Provider returns in the response body of the Authorization request the status `undefined` and the `paymentURL`.
5. Checkout redirects the customer to the `paymentURL` webpage.
6. On the `paymentURL` webpage, the customer interacts with the provider's interface.
7. Provider captures the input of customer interaction.
8. Provider [responds](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/createpayment%23callbacks) to `callbackURL` with final authorization status (`approved` or `denied`).
9. Provider redirects the customer to the `returnURL` webpage.

> The content of the `paymentURL` parameter has to include the complete URL to properly redirect the customer to the desired webpage, including the endpoint path and a code to that specific payment (e.g.: `http://php-connector.herokuapp.com/installments.php?paymentId=7ee64e51-a0d3-4405-874c-d7497ab84572`)

## Payment App

The Payment App purchase flow is a flexible option used to allow customers to go through a custom payment experience without leaving the store.

This model applies to a large variety of payment methods thanks to its interaction with the Checkout API. However, Payment Apps must be developed and deployed using [VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-vtex-io). For more information, check our [Payment App guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/payments-integration-payment-app).

## Operations in the payment flow

The following operations define the patterns of interaction between the Payment Provider and the VTEX Payments Gateway:

* Authorization
* Cancellation or Refund
* Settlement

When a customer completes a purchase, this triggers the creation of a new payment request, starting with the Authorization operation.

### Authorization

As soon as the purchase is complete, the Payments Gateway sends a [POST Create Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/createpayment) request to the provider.

The payload is quite big, as it contains information such as the items in the cart, billing address, the order ID, payment methods, callbackURL, and others. More information about the endpoints and their payloads will be available in the [Implementing a Payment Provider](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-implementing-a-payment-provider) article.

After that, the provider should respond to the request. If the payment cannot be processed right the way, the transaction status changes to `undefined`. That does not mean that the payment was canceled or denied, it is just being evaluated.

The system can retry the call asynchronously for seven days until the payment is indeed processed. During this period, VTEX will assume that the payment is “pending".

To break this cycle of asynchronous retries, there are two possible flows depending if the integration uses VTEX IO infrastructure or not:

* **Without VTEX IO (developed in the partner's infrastructure)**: when the provider gets an updated payment status, it will use a **notification** endpoint from the `callbackURL` parameter to change the payment status in the Gateway to `authorized` or `denied`. Both responses end the authorization flow.
* **With VTEX IO**: when the provider gets an updated payment status, it will read the `callbackURL` parameter to call a **retry** endpoint. Then, the Gateway makes another Create Payment request to obtain the new status defined by the provider, which will be `authorized` or `denied`. Both responses end the authorization flow.

#### Callback URL

The `callbackUrl` field contains a URL that the payment provider uses to make a callback and inform our gateway of the final payment status: `approved` or `denied`.

This URL has some query parameters, including the `X-VTEX-signature`. This parameter is mandatory and contains a signature token to identify that the request has been generated from VTEX as a security measure. The signature token has at most 32 characters. You can check an example of callback URL with the signature token below:

`1

https://gatewayqa.vtexpayments.com.br/api/pvt/payment-provider/transactions/8FB0F111111122222333344449984ACB/payments/A2A9A25B11111111222222333327883C/callback?accountName=teampaymentsintegrations&X-VTEX-signature=R123456789aBcDeFGHij1234567890tk

`

In the [Transactions page of the Admin](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/how-to-view-the-orders-details--tutorials%5F452), the signature token appears masked for security reasons, as in this example: `X-VTEX-signature=Rj******tk`.

When making the callback request, we recommend that payment providers use the callback URL exactly as received, which guarantees that all the parameters are included.

#### Mode-off

Mode-off status is a native reliability feature that allows VTEX to track the payment health and stability of their partners, ensuring that the system will not cancel orders due to instabilities.

When VTEX identifies consecutive errors in its payment partners’ integrations — more than five errors over the last five minutes — the mode-off status is activated to handle credit card transactions.

While the mode-off status is activated, all transactions that allow an asynchronous flow will be retained. During this period, the transaction remains in `authorizing` status.

This process takes an average of two hours and can hold up to two thousand requests. If the provider’s system returns to stability, the mode-off status is deactivated and our system will run processing reattempts for the transactions on standby.

For more information and frequently asked questions, refer to the [Mode-Off: FAQ](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/mode-off-faq--6hbd7PuvoxuRbPCvTqjxeB) article in our Help Center.

### Cancellation or refund

The cancellation flow starts if the order is canceled for any reason. When an order is canceled, it activates the process to cancel the order’s payment as well.

In this case, there are two scenarios:

* The payment was approved and already settled.
* The payment was not approved.

#### Payment approved and settled

When a payment is approved and already settled but canceled after that, VTEX makes the call [POST Refund Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments/-paymentId-/refunds) to the payment provider. Also, the Payment Provider Protocol accepts partial refunds when necessary.

Regardless of the provider's response, VTEX will end the transaction with the status `canceled`.

#### Payment approved but not settled

When a payment is approved but canceled before being settled, VTEX makes the call [POST Cancel Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments/-paymentId-/cancellations) to the payment provider.

Regardless of the provider's response, VTEX will end the transaction with the status `canceled`.

#### Payment not approved

VTEX sends the [POST Cancel Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments/-paymentId-/cancellations) request to the payment provider once there is no need to refund a payment that was not settled.

If the provider does not authorize the payment cancellation and returns a response with an `undefined` status, the flow will run asynchronously for a day. If the provider does not respond after this period, the payment will be canceled.

### Settlement

Once the gateway authorizes the payment, VTEX sends the [POST Settle Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments/-paymentId-/settlements) request to the provider. If the provider does not authorize the settlement right the way, the request will keep running asynchronously for a day.

During this period, when the provider responds to the call authorizing the settlement, VTEX’s platform changes the transaction status to `finished` and completes the flow.

If after one day of retries the request fails, the payment will be canceled.

## Communication in the payment flow

When using synchronous communication, VTEX will communicate with the payment provider during the purchase flow and this will determine whether the payment was approved or not.

When using asynchronous communication, VTEX will wait for a longer period of time for approval from the payment provider. This is the case of bank invoice (boleto bancário/Brazil), for example, where the shopper is expected to have a few days to pay for their order through their bank.

Depending on the payment method selected, three endpoints in the payment flow might use synchronous or asynchronous communication:

* [POST Create Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments)
* [POST Cancel Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments/-paymentId-/cancellations)
* [POST Settle Payment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/payment-provider-protocol%23post-/payments/-paymentId-/settlements)

Since the selection of payment method depends on the customer, **your provider must be prepared to receive multiple repeated requests** in those endpoints.

Contributors

2

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

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

Contributors

2

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

ON THIS PAGE

[Transparent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23transparent)

[Redirect](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23redirect)

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

[Operations in the payment flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23operations-in-the-payment-flow)

[Authorization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23authorization)[Cancellation or refund](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23cancellation-or-refund)[Settlement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23settlement)

[Communication in the payment flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23communication-in-the-payment-flow)

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-purchase-flows.md)

Copy page

On this page

ON THIS PAGE

[Transparent](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23transparent)

[Redirect](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23redirect)

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

[Operations in the payment flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23operations-in-the-payment-flow)

[Authorization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23authorization)[Cancellation or refund](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23cancellation-or-refund)[Settlement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23settlement)

[Communication in the payment flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/payments-integration-purchase-flows/docs/guides/payments-integration-purchase-flows%23communication-in-the-payment-flow)

On this page

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


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

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

[Assistant]
Documentation

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

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

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

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

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

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

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

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

VTEX IO Apps

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

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

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

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

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

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

---

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

VTEX IO Apps

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

---

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

Yotpo Reviews Integration

Official extension

Version: 1.2.1

Latest version: 1.2.1

The Yotpo Reviews Integration app is a product review and rating integration with [Yotpo](https://read.calvincode.net/reader?url=https://www.yotpo.com/).

![{"base64":"  ","img":{"width":992,"height":384,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":22977,"url":"https://user-images.githubusercontent.com/6306265/71126858-d7b64580-21b7-11ea-8d88-c8ef90b3ad41.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/6306265/71126858-d7b64580-21b7-11ea-8d88-c8ef90b3ad41.png)

## Configuration

1. [Install](https://read.calvincode.net/reader?url=https://vtex.io/docs/recipes/store/installing-an-app) the `yotpo` app in the desired account;
2. In the admin's account, access **Apps** and then select the **Yotpo Integration** box;

![{"base64":"  ","img":{"width":1104,"height":611,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":90688,"url":"https://user-images.githubusercontent.com/6306265/71126888-e997e880-21b7-11ea-88da-287ab588d2a6.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/6306265/71126888-e997e880-21b7-11ea-88da-287ab588d2a6.png)

1. Once in the app's page, define the app’s configurations in the **setup** section:

![{"base64":"  ","img":{"width":658,"height":318,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":14539,"url":"https://user-images.githubusercontent.com/6306265/71126932-016f6c80-21b8-11ea-9af5-7f6da2b3ad9b.png"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/6306265/71126932-016f6c80-21b8-11ea-9af5-7f6da2b3ad9b.png)

* **Yotpo App Key**: Enter the app key that you have received from Yotpo's admin interface.
* **Use Reference Id**: Check this box if you wish to use the product's reference id rather than its product id to link the product to its reviews.

:warning: This app fills the standard VTEX review blocks with content using abstract interfaces from `vtex.product-review-interfaces` . The **VTEX review blocks** are:

* `"product-reviews"`: This block can be added to the product page (`store.product`). It renders the main Yotpo widget which lists any reviews or answered questions for the product being viewed as well as a form to add a new review or ask a new question.
* `"product-rating-summary"`: This block can be added to the product page (`store.product`) and renders the average rating for the product being viewed as well as the number of reviews that have been submitted.
* `"product-rating-inline"`: Similar to the previous block, but intended to be used in product shelves.

Additional **Yotpo review blocks** are:

* `"yotpo-all-reviews"`: This block can be added to a custom page (`store.custom`). It allows you to display all your site and product reviews in one page by rendering a [Yotpo widget](https://read.calvincode.net/reader?url=https://support.yotpo.com/en/article/generic-other-platforms-adding-yotpo-reviews-to-a-dedicated-page).

This app also includes a pixel integration to send order conversation tracking data to Yotpo.

## Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on [Using CSS Handles for store customization](https://read.calvincode.net/reader?url=https://vtex.io/docs/recipes/style/using-css-handles-for-store-customization).

| CSS Handles            |
| ---------------------- |
| reviewsContainer       |
| ratingSummaryContainer |
| ratingInlineContainer  |
| allReviewsContainer    |

See also

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

ON THIS PAGE

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.yotpo/docs/apps/vtex.yotpo%23configuration)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.yotpo/docs/apps/vtex.yotpo%23customization)

Was this helpful?

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