Configuração do conector CieloEcommerce na VTEX

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:

⚠️
Ao final da configuração do conector CieloEcommerce, é necessário instalar o aplicativo Connector CieloEcommerce.

Configuração inicial do conector CieloEcommerce

Acesse o painel administrativo da sua loja VTEX: https://nomedaloja.myvtex.com/admin
Clique em Configurações da loja > Provedores;
Clique em Novo provedor;

Pesquise por CieloEcommerce e selecione o conector.

Insira os dados da sua conta Cielo:

Informe as credenciais da sua conta Cielo:

Chave de Aplicação: Merchant ID;
Token de aplicação: Merchant Key.

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..

ℹ️
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.

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)

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.

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.

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.

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..

ℹ️
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.

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.

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.

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.

Autenticação 3DS

Para usar a autenticação 3DS, é necessário baixar o aplicativo na 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.

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 Cielo. Campo obrigatório para transações com autenticação 3DS 2.2e DataOnly.
MpiClientSecret	Chave secreta do MPI, disponibilizada pela Cielo. Campo obrigatório para transações com autenticação 3DS 2.2 e DataOnly
MpiMerchantName	Nome da loja, conforme cadastrado na Cielo. 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 Cielo. Campo obrigatório para transações com autenticação 3DS 2.2 e DataOnly
MpiEstablishmentCode	Código de estabelecimento da loja, disponibilizado pela Cielo. 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. 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.

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.
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.
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.

📘
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.

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.

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.

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.

Tokenização

O conector CieloEcommerce oferece tokenização 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 a tokenização, configure o campo SaveCard como true:

Campo	Descrição
SaveCard	Habilita a tokenização de cartões para transações recorrentes: True: habilita a tokenização; False: desabilita a tokenização.

Campo

Descrição

SaveCard

Habilita a tokenização de cartões para transações recorrentes:

True: habilita a tokenização;
False: desabilita a tokenização.

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.

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.

Configuração do conector CieloEcommerce na VTEX

Ao final da configuração do conector CieloEcommerce, é necessário instalar o aplicativo Connector CieloEcommerce.

Configuração inicial do conector CieloEcommerce

Importante

Exemplos de nome da afiliação

Integration

Provider

Se o contrato for para múltiplos provedores, a integração será via Gateway de Pagamento.

Atenção

Boleto Bancário

Split de Pagamento

Autenticação 3DS

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

Antifraude

Campos de configuração

Regra para configuração dos MDDs personalizados

Captura de transações

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.

VerifyCard

Tokenização

Cancelamento e estorno

Configurações específicas