--- updatedAt: 2026-10-14T21:17:04.000Z agentTools: siteIndex: https://docs.cielo.com.br/llms.txt projectIndex: https://docs.cielo.com.br/conectores/llms.txt --- # Configuração do conector CieloEcommerce na VTEX Configure o conector para transacionar online. A configuração do conector **CieloEcommerce** na VTEX é necessária para habilitar o processamento de pagamentos por meio da **API E‑commerce Cielo** ou do **Gateway de Pagamento**, de acordo com a solução contratada. A configuração envolve as seguintes etapas e grupos de parâmetros: * [Configuração inicial do conector *CieloEcommerce*](https://docs.cielo.com.br/conectores/docs/vtex-conector#configura%C3%A7%C3%A3o-inicial-do-conector-cieloecommerce); * [Boleto bancário](https://docs.cielo.com.br/conectores/docs/vtex-conector#boleto-banc%C3%A1rio); * [Split de pagamento](https://docs.cielo.com.br/conectores/docs/vtex-conector#split-de-pagamento); * [Expiração do QR Code Pix](https://docs.cielo.com.br/conectores/docs/vtex-conector#expira%C3%A7%C3%A3o-do-qr-code-pix); * [Autenticação 3DS](https://docs.cielo.com.br/conectores/docs/vtex-conector#autentica%C3%A7%C3%A3o-3ds); * [Soft Descriptor](https://docs.cielo.com.br/conectores/docs/vtex-conector#soft-descriptor); * [Antifraude](https://docs.cielo.com.br/conectores/docs/vtex-conector#antifraude); * [Captura de transações](https://docs.cielo.com.br/conectores/docs/vtex-conector#captura-de-transa%C3%A7%C3%B5es); * [VerifyCard](https://docs.cielo.com.br/conectores/docs/vtex-conector#verifycard); * [Recorrência](https://docs.cielo.com.br/conectores/docs/vtex-conector#tokeniza%C3%A7%C3%A3o); * [Cancelamento e estorno](https://docs.cielo.com.br/conectores/docs/vtex-conector#cancelamento-e-estorno); * [Configurações específicas](https://docs.cielo.com.br/conectores/docs/vtex-conector#configura%C3%A7%C3%B5es-espec%C3%ADficas). ### Ao final da configuração do conector CieloEcommerce, é necessário instalar o aplicativo **Connector CieloEcommerce**. ![](https://files.readme.io/be7b9f0024b13393fc57ac3438ec500278b4ab31bb1e1386e829c9ba150dc06c-image.png) Sempre que uma nova versão do Conector Cielo E-commerce estiver disponível, **recomendamos sua atualização** para garantir acesso às melhorias e novas funcionalidades. Caso não atualize, isso **não vai gerar impactos transacionais**, mas versões mais recentes podem incluir novos recursos e configurações. Alterações de chaves, por si só, **não exigem a atualização ou reinstalação do aplicativo**. ## Configuração inicial do conector *CieloEcommerce* 1. Acesse o painel administrativo da sua loja VTEX: `https://nomedaloja.myvtex.com/admin` 2. Clique em **Configurações da loja** > **Provedores**; 3. Clique em **Novo provedor**; ![Tela de criação de novo provedor na VTEX.](https://files.readme.io/2cf2113fb3a7913db4f5d075e23aee5086504417a18fc05736b399b6fb921b6a-image.png) 4. Pesquise por **CieloEcommerce** e selecione o conector. Pesquisa do conector "CieloEcommerce" nos conectores disponíveis na VTEX 5. Informe as credenciais: * **Chave de Aplicação**: `Merchant ID`; * **Token de aplicação**: `Merchant Key`. **Para integração API E-commerce Cielo**, o acesso ao `Merchant ID` e `Merchant Key` é realizado no Site Cielo. Veja como obter as credenciais em Revogar e criar credenciais no site Cielo. **Para integração Gateway de Pagamento**, o acesso ao `Merchant ID` e `Merchant Key` é realizado no [Portal E-commerce](https://portal.cielo.com.br/). Veja como obter as credenciais em [Como gerar credencial do Gateway de Pagamento?](https://docs.cielo.com.br/atendimento/docs/como-gerar-credencial-do-gateway-de-pagamento) ### Importante Após gerar o token, a **loja deve armazená-lo** em um local seguro. Por motivos de segurança, a VTEX **não exibirá o token novamente**. 6. No campo **Nome**, informe um identificador que faça referência à Cielo, facilitando a identificação da afiliação no futuro. #### Exemplos de nome da afiliação | Exemplo | Definição | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | CieloEcommerce - Ticket | Afiliação que usa Ticket como provedor. | | CieloEcommerce - Cielo30 c/ 3DS c/ SPLIT | Afiliação que usa o Gateway de Pagamento, com autenticação 3DS (se compatível) e Split de Pagamento (se compatível) | 7. Ative o **modo teste** para validar a integração antes de utilizá-la em produção. O modo de teste é **opcional**, mas deve ser ativado para validar as integrações no ambiente sandbox. 8. Caso utilize Split de Pagamento, **ative** a opção de **split de recebíveis** e defina: * Quem será responsável pelas tarifas de processamento; * Quem será responsável pelos estornos. ![Configuração de modo teste, split de recebíveis e definição de responsáveis por tarifas.](https://files.readme.io/a51f40d89b978e8420cdddf7d59519d7fb5697d8b44eae9de4a3c971c82197e9-image.png) 9. Após concluir as configurações iniciais, preencha os **campos do provedor** conforme a ordem exibida na VTEX. Os campos `Integration` e `Provider` definem como a afiliação será processada pela VTEX e impactam diretamente as configurações dos meios de pagamento. #### Integration Define o modelo de integração da afiliação: * **Adquirência**: quando a integração é realizada diretamente com a **API E‑commerce Cielo**. * **Gateway**: quando a afiliação faz parte do modelo de **Gateway de Pagamento**, permitindo o uso de múltiplos provedores. #### Provider Define o provedor responsável pelo processamento do pagamento nesta afiliação. O valor deste campo deve ser preenchido de acordo com o **modelo de integração selecionado no campo **`Integration` e o **provedor efetivamente configurado na operação**. | Cenário | Como definir o Provider | | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Integration` = Adquirência | Insira "Cielo". | | `Integration` = Gateway | Informe o **provedor utilizado no Gateway de Pagamento**, conforme configuração.
Veja os provedores disponíveis. | | Testes | Insira "Simulado". |
| Provedor | Quando selecionar | | ------------ | ---------------------------------------------------------------------------------------------- | | **Simulado** | Indicado para testes da integração antes de colocar a loja em produção. | | **Cielo** | Deve ser selecionado quando a afiliação estiver configurada com **Integration = Adquirência**. | | **Cielo30** | Deve ser selecionado quando a afiliação estiver configurada com **Integration = Gateway**. | Com esses parâmetros definidos, prossiga com o preenchimento dos demais campos conforme a ordem apresentada na VTEX.. ![Campos de configuração do conector na VTEX](https://files.readme.io/899d6d9839e4999c997117a337d3009d3e96e17109466b36002f81e92173dcda-image.png) ### Se o contrato for para **múltiplos provedores**, a integração será via **Gateway de Pagamento**. Se o contrato for **exclusivamente com a Cielo**, a integração será **Cielo**. ### Atenção Caso seja necessário alterar as credenciais `MerchantID` e `MerchantKey` em um conector já existente, certifique-se de preencher todos os campos abaixo. Se algum campo permanecer sem configuração, uma mensagem de erro será exibida. ## Boleto Bancário O campo `DaysToInvoiceCancel` configura o comportamento de **cancelamento automático** de transações pagas por **boleto bancário** que não forem liquidadas até a data de vencimento. As regras de funcionamento e particularidades do meio de pagamento estão descritas em [meios de pagamento](https://docs.cielo.com.br/conectores/docs/meios-de-pagamento-vtex#boleto). Nesta etapa, apenas os parâmetros técnicos do conector são definidos. | Campo | Descrição | | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **DaysToInvoiceCancel** | Para pagamentos via **Boleto Bancário** não pagos, selecione a quantidade de dias corridos após o vencimento para que a transação seja cancelada. Quando selecionado **Not defined**, é aplicado o prazo padrão de 30 dias corridos. | ## Split de Pagamento Define os parâmetros técnicos para habilitar o **Split de Pagamento** no conector **CieloEcommerce**. Neste ponto, apenas as opções de configuração do conector são definidas. As regras de negócio e os cenários de uso estão descritos na página de [funcionalidades VTEX](https://docs.cielo.com.br/conectores/docs/funcionalidades-vtex#split-de-pagamento).
Campo Descrição
**IsSplit** Define se a afiliação fará **uso de Split de Pagamento**. Informe **Sim** para habilitar a divisão dos recebíveis ou **Não** para desabilitar. Disponível para os tipos de pagamento crédito, débito e boleto.
**useCieloMDR** Disponível apenas quando o split está habilitado. Define como as taxas de processamento serão tratadas: - **True**: aplica a taxa cadastrada na Cielo; - **False**: zera a taxa para o seller. Se não usar o Split de Pagamentos, selecione **Not Defined**.
## Expiração do QR Code Pix Permite configurar o tempo para expiração de um QR Code Pix.
Campo Descrição
**QRCodeExpiration** Campo para configurar o tempo para expiração do QR Code Pix em minutos. - **Valor mínimo**: 15 minutos; - **Valor máximo**: 60 minutos; - **Valor padrão**: 60 minutos.
A VTEX exibe o tempo em segundos, mas o valor deve ser inserido em minutos. ## Autenticação 3DS Para usar a autenticação 3DS, [é necessário baixar o aplicativo na VTEX](https://docs.cielo.com.br/conectores/docs/autenticacao-3ds-vtex). Configura os parâmetros técnicos da **Autenticação 3DS** no conector **CieloEcommerce**. A configuração da autenticação 3DS é obrigatória para transações de débito. As regras de negócio estão descritas em [funcionalidades VTEX](https://docs.cielo.com.br/conectores/docs/funcionalidades-vtex#autentica%C3%A7%C3%A3o-3ds).
Campo Descrição
**UseMPI** Define se a **Autenticação 3DS 2.2** estará ativa na afiliação. - **True**: habilita a Autenticação 3DS; - **False**: desabilita a Autenticação 3DS. Este campo é **obrigatório para o tipo de pagamento débito**.
**MpiClientId** Identificador do MPI, disponibilizado pela adquirente.
**Campo obrigatório para transações com autenticação 3DS 2.2e DataOnly**.
**MpiClientSecret** Chave secreta do MPI, disponibilizada pela adquirente.
**Campo obrigatório para transações com autenticação 3DS 2.2 e DataOnly**
**MpiMerchantName** Nome da loja, conforme cadastrado na adquirente.
**Campo obrigatório para transações com autenticação 3DS 2.2 e DataOnly**
**MpiCancelOnFailure** Define o comportamento quando ocorre erro na **primeira etapa** da autenticação: - **True** (padrão): transação será cancelada em caso de falha na autenticação; - **False**: transação continua mesmo em caso de falha na autenticação.
**MpiCancelOnECIDowngrade** Define o comportamento quando ocorre erro na **segunda etapa** da autenticação: - **True** (padrão): transação será cancelada em caso de falha na autorização da autenticação; - **False**: transação continua mesmo em caso de falha na autorização da autenticação.
**MpiMCC** Merchant Category Code (MCC) da loja, disponibilizado pela adquirente.
**Campo obrigatório para transações com autenticação 3DS 2.2 e DataOnly**
**MpiEstablishmentCode** Código de estabelecimento da loja, disponibilizado pela adquirente.
**Campo obrigatório para transações com autenticação 3DS 2.2 e DataOnly**
**DataOnly** Define o uso do modo **Data Only** dentro da **Autenticação 3DS**. Nesse modo, a transação é enviada **sem desafio de autenticação**. - **True**: utiliza o modo Data Only, com responsabilidade de chargeback da loja; - **False**: utiliza o fluxo padrão de autenticação 3DS; - **Not defined**: não aplica o modo Data Only. O uso de Data Only requer a Autenticação 3DS habilitada (**UseMPI = True**) e o preenchimento de todos os campos obrigatórios do MPI.
### Os campos relacionados ao MPI podem ser preenchidos antecipadamente, mesmo com o **UseMPI** desativado. Para ativar o 3DS posteriormente, basta alterar o valor desse campo. ## Soft Descriptor Configura o **texto exibido na fatura do comprador** junto ao nome da loja para pagamentos processados pelo conector **CieloEcommerce**. As regras de exibição e eventuais impactos na identificação da compra estão estão descritas em [funcionalidades VTEX](https://docs.cielo.com.br/conectores/docs/funcionalidades-vtex#soft-descriptor). Nesta etapa, apenas o parâmetro técnico do conector é definido. | Campo | Descrição | | :----------------- | :----------------------------------------------------------------------------------------------------- | | **SoftDescriptor** | Texto exibido na fatura do comprador. Permite **até 13 caracteres** e não aceita caracteres especiais. | ## Antifraude Configura os parâmetros técnicos relacionados ao uso de **Antifraude** no conector **CieloEcommerce**. Nesta etapa, são definidos apenas os provedores e os fluxos de análise aplicados às transações. As regras de negócio, critérios de risco e responsabilidades estão descritos descritas em [funcionalidades VTEX](https://docs.cielo.com.br/conectores/docs/funcionalidades-vtex#antifraude). Para usar o Antifraude, é necessário configurar o Fingerprint. Veja como configurar o Fingerprint para: * Provedor Cybersource; * Provedor ClearSale. #### Campos de configuração
Campo Descrição
**UseAntifraudSolution** Selecione qual opção de Antifraude será usada: - **Without Antifraud**: para não usar Antifraude; - **Cielo**: para usar Antifraude integrado a Cielo; - **VTEX**: para usar Antifraude gerenciado pela VTEX.
**AntifraudProvider** Define o provedor de Antifraude contratado pelo lojista. Este campo **deve ser preenchido apenas** quando o uso de Antifraude estiver habilitado e o serviço tiver sido **contratado com o comercial da Cielo ou do Gateway de Pagamento**. - **Not Defined**: elecionar quando não houver uso de Antifraude ou quando o Antifraude contratado não for fornecido pela Cielo; - **Cybersource**: selecionar quando o Antifraude **Cybersource** estiver contratado com a Cielo; - **ClearSale**: selecionar quando o Antifraude **ClearSale** estiver contratado com a Cielo.
**Antifraud** Define o fluxo de análise de fraude aplicado às transações: - **AnalyseFirst**: a análise de fraude ocorre antes da autorização; - **AuthorizeFirst**: a análise de fraude ocorre após a autorização.
**AntifraudSequenceCriteria** Selecione a sequência do fluxo de antifraude de acordo com a escolha da análise: - **AuthorizeFirst**: **Always** (sempre analisa) ou **OnSuccess** (analisa apenas transações autorizadas); - **AnalyseFirst**: **Always** (sempre autoriza) ou **OnSuccess** (autoriza apenas se a análise for aprovada).
**CaptureOnLowRisk** Define se a transação deve ser capturada automaticamente quando for classificada como **baixo risco** pelo Antifraude. - **True**: autoriza a seguir com a captura após a aprovação no Antifraude; - **False**: não realiza a captura automaticamente, mesmo em casos de baixo risco; - **Not defined**: selecionar quando o Antifraude não estiver habilitado. Veja mais detalhes no item [Captura](https://docs.cielo.com.br/conectores/docs/vtex-conector#captura-de-transa%C3%A7%C3%B5es).
**VoidOnHighRisk** Define se a transação deve ser automaticamente cancelada quando for classificada como **alto risco** pelo Antifraude. - **True**: autoriza o cancelamento automático de transações rejeitadas no Antifraude; - **False**: não realiza o cancelamento automático; - **Not defined**: selecionar quando o Antifraude não estiver habilitado. Veja mais detalhes no item [Cancelamento](https://docs.cielo.com.br/conectores/docs/vtex-conector#cancelamento-e-estorno).
**CustomMdds** Campo exclusivo para lojas que usam o Antifraude integrado com o provedor **Cybersource**. Permite o envio de **MDDs personalizados (85 a 89)** para enriquecer a análise antifraude com informações adicionais da transação. Os MDDs devem estar **previamente configurados na Cybersource**. Caso contrário, os dados informados neste campo não serão considerados na análise antifraude.
### Importante Se a loja já possui uma configuração de Antifraude previamente habilitada, selecionar **Without Antifraud** no campo **UseAntifraudSolution** não é suficiente para interromper o envio das transações para análise. Para desativar completamente o Antifraude nesse cenário, também é necessário: - Deixar sem seleção os campos **AntifraudProvider**, **Antifraud** e **AntifraudSequenceCriteria**; - Definir **CaptureOnLowRisk** e **VoidOnHighRisk** como **Not Defined**. ### Regra para configuração dos MDDs personalizados Para configurar os MDDs personalizados, é obrigatório seguir o padrão abaixo: `{Número}:{Valor}` Onde: - `{Número}` corresponde ao número do MDD configurado na Cybersource (de 85 a 89); - `{Valor}` corresponde ao nome do campo descritivo que será enviado, conforme encontrado nesta documentação. **Exemplo:**
85:shopperinteraction Para enviar mais de um MDD, utilize o mesmo padrão, separando cada par por vírgula: `85:shopperinteraction,86:currency` Erros na grafia do campo `{Valor}` não impedem o processamento da transação, porém os dados não serão enviados para a Cybersource. ## Captura de transações Configura os parâmetros técnicos que definem **quando e como a transação será capturada** no conector **CieloEcommerce**.
Campo Descrição
**Captura** Define o momento em que a solicitação de captura será enviada. - **Padrão** ou **Desativado**: a captura ocorre automaticamente após quatro dias. - **Imediatamente**: a captura ocorre logo após a autorização. O prazo máximo para captura é de **sete dias (168 horas)**. Quando o Antifraude estiver habilitado, a captura respeita o resultado da análise e ocorre apenas após aprovação.
O campo **Captura** define apenas o momento da captura. O comportamento de captura ou cancelamento automático com base na análise de risco é controlado pelos campos **CaptureOnLowRisk** e **VoidOnHighRisk**, configurados na seção [Antifraude](https://docs.cielo.com.br/conectores/docs/funcionalidades-vtex#antifraude). ## VerifyCard Configura os parâmetros técnicos do **VerifyCard** no conector **CieloEcommerce**. Nesta etapa, apenas as opções de verificação prévia de cartão são definidas. As regras de funcionamento, objetivos da funcionalidade e impactos na aprovação de transações estão descritos na página de [funcionalidades VTEX](https://docs.cielo.com.br/conectores/docs/funcionalidades-vtex#verifycard). | Campo | Descrição | | :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | | **UseVerifyCard** | Selecione para utilizar o serviço de VerifyCard .
Antes de configurar, confira se essa funcionalidade está habilitada em sua loja/EC. | | **AcceptInternationalCard** | Escolha se a loja aceitará cartões internacionais. | | **AcceptPrepaidCard** | Escolha se a loja aceitará cartões pré-pagos. | ## Recorrência O conector CieloEcommerce permite que a Cielo salve dados de cartões exclusivamente para recorrências configuradas com a VTEX. Para saber como criar uma recorrência, consulte a documentação oficial da VTEX. Para habilitar o armazenamento de cartões pela Cielo, configure o campo `SaveCard` como true:
Campo Descrição
**SaveCard** Habilita o armazenamento de cartões pela Cielo para transações **recorrentes**: - **True**: habilita o armazenamento ; - **False**: desabilita o armazenamento.
> Os dados dos cartão são armazenados pela Cielo e não são compartilhados com o estabelecimento. ## Cancelamento e estorno Configura os parâmetros técnicos que definem como o **cancelamento e o estorno de transações serão tratados** no conector CieloEcommerce. Nesta etapa, é definido apenas o fluxo de autorização do cancelamento/estorno no conector.
Campo Descrição
**CancelRefundType** Define o fluxo de cancelamento ou estorno de pedidos: - **Automático sempre que possível:** autoriza o cancelamento e o estorno de forma automática (fluxo padrão). - **Manual de acordo com a loja (notificação por e-mail):** solicitações de cancelamento e estorno não são autorizadas automaticamente, e a loja é notificada por e-mail para análise.
## Configurações específicas Reúne campos aplicáveis a cenários específicos de integração, que não impactam o fluxo padrão de pagamentos no e‑commerce. Na maioria das operações de e‑commerce, esses campos não exigem configuração e podem permanecer em branco ou desabilitados. | Campo | Descrição | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **CieloLIOClientId** | Campo destinado exclusivamente à integração com o **SalesApp (Cielo LIO)**. Quando o conector é usado apenas para e‑commerce, este campo deve permanecer em **branco**. |