FAQ — Nova integração do MPI Cielo

Perguntas frequentes sobre a nova integração do MPI Cielo (V3) e o protocolo de autenticação 3DS.

Sobre o produto

O que é o novo MPI Cielo (V3)?

O MPI V3 é o novo modelo de integração do plugin de autenticação 3DS da Cielo. Ele opera exclusivamente no modelo server-to-server: o estabelecimento controla todas as chamadas à API no back-end, incluindo a exibição do desafio ao portador quando necessário.

O MPI V3 muda a versão do protocolo 3DS?

Não. O MPI V3 é uma evolução do plugin de integração, não do protocolo. As versões do protocolo 3DS continuam as mesmas:

Quem pode usar o MPI V3?

O MPI V3 é exclusivo para clientes com certificação PCI DSS que tenham o produto 3DS habilitado na Cielo.

Sobre a migração

Preciso migrar para o novo MPI Cielo V3? A integração V2 continua funcionando?

A integração V2 será descontinuada. A migração para o MPI V3 é obrigatória para todos os estabelecimentos que utilizam autenticação 3DS. Respeite o prazo informado pela Cielo para evitar interrupção no processamento de pagamentos.

A migração para o MPI Cielo V3 afeta meus clientes finais?

Não diretamente. A experiência do portador permanece a mesma: o desafio 3DS continua sendo exibido quando necessário, sem alteração visual ou de comportamento para o comprador. O que muda é a implementação no back-end e no front-end do estabelecimento.

Preciso solicitar novas credenciais para usar o MPI Cielo V3?

Não. As credenciais (ClientId e ClientSecret) usadas para gerar o access_token são as mesmas. O que muda é o endpoint de AUTH: de /v2/auth/token para /v3/auth/token.

Posso rodar as versões do MPI V2 e V3 em paralelo durante a migração?

Não é recomendado rodar os dois modelos simultaneamente para o mesmo pedido. Os scripts são incompatíveis entre si. Planeje a migração como uma substituição completa: remova os scripts e classes V2 e implemente o fluxo V3 integralmente.

O que acontece com transações em andamento durante a troca de versão?

Transações iniciadas com a V2 devem ser concluídas com a V2. Não valide com V3 uma autenticação iniciada com V2. Planeje a ativação da V3 em um momento de baixo volume para minimizar o impacto.

Quanto esforço de desenvolvimento a migração exige?

Depende da implementação atual. De forma geral:

• Front-end: remova os inputs com classes bpmpi_*, substitua os scripts e implemente a inicialização via MPI.load() e MPI.init().
• Back-end: mova a geração do access_token e as chamadas de ENROLL e VALIDATE para o servidor, caso ainda não estejam lá. Atualize o endpoint de AUTH.

A migração envolve mudança de paradigma (de front-end para server-to-server). Planeje tempo de desenvolvimento, testes e homologação.

Ambiente e configuração

Qual a diferença entre sandbox e produção?

O sandbox é o ambiente de testes. Use-o para validar a integração antes de ir para produção. Transações em produção são reais, geram custos e podem resultar em penalizações pelas bandeiras e pelos emissores.

Onde encontro os endpoints de sandbox e produção?

Qual script JavaScript devo incluir na página de checkout?

Inclua os dois scripts abaixo no ambiente correspondente:

• mpi.js — responsável pela inicialização da sessão, atualização do cartão e exibição do desafio;
• mpiHelpers.js — fornece utilitários como getBrowserInfo e o builder de pedido.

Consulte a Etapa 1 – Preparar o front-end para ver os endereços completos.

Tokens e autenticação

Como gerar as crendenciais de ClientId e ClientSecret?
As credenciais são geradas através do site Cielo. Saiba mais em: Obter as credenciais 3DS

Qual a diferença entre access_token e token?

São dois tokens distintos com finalidades diferentes:

Importante: nunca exponha o access_token no front-end.

Por quanto tempo o access_token é válido?

O access_token tem validade de 20 minutos (1.200 segundos) em produção. Se ele expirar antes de a sequência ser concluída, as chamadas subsequentes retornarão 401. Nesse caso, gere um novo access_token e reinicie o fluxo desde o AUTH.

Para evitar esse cenário, gere um novo access_token a cada sessão de compra e monitore o campo expires_in da resposta AUTH.

O que fazer quando recebo o erro 401?

Regere o access_token chamando novamente a operação AUTH e reinicie o fluxo.

Fluxo de integração

Qual é a sequência obrigatória das operações?

A sequência é obrigatória e não pode ser alterada:

1. AUTH — obter o access_token (back-end);
2. INIT — inicializar a sessão e obter o token e o referenceId (back-end);
3. MPI.load e MPI.init — carregar e inicializar o script (front-end);
4. MPI.updateCard — atualizar o número do cartão (front-end);
5. ENROLL — autenticar o cartão (back-end);
6. MPI.challenge — exibir o desafio ao portador, se necessário (front-end);
7. VALIDATE — validar a autenticação após o desafio (back-end).

Atenção: a API bloqueia chamadas fora de ordem e chamadas repetidas.

O que significa cada status retornado pelo ENROLL?

O status 2 pode ser retornado no VALIDATE?

Não. Na operação VALIDATE, apenas os status 0 e 1 são retornados. O status 2 é exclusivo do ENROLL.

O que devo fazer quando o ENROLL retornar Status = 2?

Exiba o desafio ao portador usando MPI.challenge(challengeData, order). Após a conclusão, o callback onValidationRequired é acionado com o TransactionId. Envie esse valor ao back-end e execute o VALIDATE.

O que devo fazer quando o ENROLL retornar Status = 0?

Consulte o ECI retornado na resposta para decidir se prossegue com a transação. Um ECI baixo indica autenticação não realizada e pode resultar em maior taxa de recusa ou responsabilidade por fraude (chargeback) do lado do estabelecimento. Consulte a Tabela de ECI para a interpretação correta de cada valor.

Front-end e scripts

Quando devo chamar MPI.updateCard()?

Chame MPI.updateCard() antes de enviar o pedido para o ENROLL. Se o comprador trocar de cartão durante a mesma sessão, chame novamente antes de um novo ENROLL para manter a sessão sincronizada.

O que é o cardNumberReader?

É um callback de configuração do MPI.load. Ele é chamado pelo script imediatamente antes de MPI.updateCard() e deve retornar o número do cartão como string, contendo apenas dígitos.

Exemplo:

cardNumberReader: function () {
    return document.getElementById("cardNumber").value.replace(/\D/g, "");
}

Qual é a ordem dos parâmetros em MPI.init()?

A assinatura é MPI.init(referenceId, token). A ordem é obrigatória: primeiro o referenceId, depois o token retornado pelo INIT. Inverter os parâmetros causa falha silenciosa — o callback onReady não é acionado e as etapas seguintes não funcionam.

O que acontece se eu não aguardar o callback onReady antes de chamar MPI.updateCard()?

O script pode não estar pronto para processar a atualização. Aguarde o callback onReady antes de chamar qualquer método que dependa da sessão inicializada.

O que é MPIHelpers.getBrowserInfo() e por que devo usá-lo?

É um utilitário do mpiHelpers.js que coleta automaticamente os dados obrigatórios do objeto BrowserInfo a partir do navegador do comprador: userAgent, screenWidth, screenHeight, colorDepth, timeZoneOffset, language e javaEnabled. Use-o para evitar coleta manual e reduzir erros.

Erros e diagnóstico

O que causa o erro 409?

O erro 409 indica chamada fora de ordem ou chamada repetida. Respeite sempre a sequência: AUTH → INIT → ENROLL → VALIDATE.

Quais são os erros mais comuns na operação AUTH?

O que significam os Reason Codes?

Para códigos não listados, entre em contato com o suporte Cielo.

Testes no sandbox

Como testar a integração antes de ir para produção?

Use os cartões de teste disponíveis na documentação. Cada cartão simula um cenário específico:

Consulte a lista completa em Cartões de teste.

Próximos passos e documentação relacionada

Após concluir a autenticação com Status = 1, envie os dados retornados no campo Authentication para a etapa de autorização via Payment.ExternalAuthentication.

Para mais detalhes, consulte:

• Autenticação 3DS — MPI V3;
• Cartões de teste 3DS;
• Tabela de ECI.