Guia de migração para o MPI v2.1
Esta página é para lojas que já integram o script de autenticação 3DS do Merchant Plugin (MPI) v2 no checkout e precisam migrar para o MPI v2.1.
A Cielo está disponibilizando uma atualização na integração do MPI, a versão 2.1. Não há alteração na versão do protocolo 3DS.
Passo a passo
A migração tem quatro passos no front-end e nenhum no back-end:
- Troque a URL do script. Substitua
BP.Mpi.3ds20.js(ouBP.Mpi.3ds20.min.js) porBP.Mpi.3ds21.min.js, carregado direto do host do MPI. Não hospede uma cópia local. Isso impede que correções futuras cheguem ao seu checkout. As URLs de cada ambiente estão em Endereços do script. - Libere o iframe do MPI na Content-Security-Policy (CSP), caso seu checkout tenha CSP. Caso contrário, pule este passo. Veja como em Content-Security-Policy.
- Gere um
access_tokennovo a cada carregamento do checkout (não é permitido reutilizar oaccess_token). Veja como gerar o token em Criar o token de acesso. - Valide em Sandbox com
Environment= "SDB" nobpmpi_config(), seguindo o roteiro de testes em Sandbox. Depois, publique em Produção comEnvironment= "PRD".
Atenção
- No MPI 2.1, cada
access_tokensó pode ser usado uma vez. Gere um token novo a cada carregamento do checkout e não guarde um token para reutilizar em vários carregamentos.- Depois de confirmar que a integração da sua loja chega pelo MPI 2.1, o script antigo deixa de funcionar para o seu estabelecimento.
Endereços do script
O script fica no mesmo host do MPI de cada ambiente, e o valor de Environment no bpmpi_config() precisa corresponder ao host usado. A tabela a seguir mostra o valor de Environment e a URL do script em cada ambiente:
| Ambiente | Environment | URL do script |
|---|---|---|
| Sandbox | SDB | https://mpisandbox.braspag.com.br/Scripts/BP.Mpi.3ds21.min.js |
| Produção | PRD | https://mpi.braspag.com.br/Scripts/BP.Mpi.3ds21.min.js |
Insira o script no fim da página de checkout, depois da função bpmpi_config(). Exemplo de uso em Produção:
<script src="https://mpi.braspag.com.br/Scripts/BP.Mpi.3ds21.min.js" type="text/javascript"></script>
ImportanteCarregue o script sempre direto do host do MPI. Não hospede uma cópia local, para receber as correções futuras no seu checkout.
Verificar a integridade do script
Para conferir a integridade do script, compare o SHA-256 do arquivo baixado com o valor publicado em BP.Mpi.3ds21.min.js.sha256, no mesmo caminho do script. O SHA-256 é um hash: um código calculado a partir do conteúdo do arquivo, que muda sempre que o arquivo muda.
Requisitos para integração
Para usar o MPI 2.1, o checkout precisa liberar o iframe do MPI na CSP, caso tenha CSP, e ser servido em HTTPS.
Content-Security-Policy
Se o checkout publica CSP, inclua o host do MPI na diretiva frame-src. O script do MPI v2.1 abre um iframe oculto nesse host. Sem a liberação, o navegador bloqueia o iframe e a autenticação termina em onError. Exemplo de diretiva para Produção:
frame-src https://mpi.braspag.com.br;Em Sandbox, use https://mpisandbox.braspag.com.br. Se a sua CSP não tem frame-src, mas tem child-src ou default-src, faça a liberação nessa diretiva.
O restante da CSP continua como no MPI v2: o script-src continua liberando o host do MPI e os hosts do Songbird da Cardinal. O checkout não chama mais a API do MPI diretamente, então o connect-src não precisa do host do MPI.
Requisito de HTTPS
O checkout precisa ser servido em HTTPS: o iframe do MPI só aceita ser carregado por páginas HTTPS. Se a Cielo restringir os domínios que podem carregar o iframe, ela pedirá a lista de origens do seu checkout no pacote de migração, por exemplo https://www.sualoja.com.br.
O que não muda
Todo o restante da integração com o MPI v2 continua valendo, sem alteração de código. A tabela a seguir resume cada item e como ele fica no MPI v2.1:
| Item | Como fica no MPI v2.1 |
|---|---|
Geração do token (POST /v2/auth/token), descrita em Criar o token de acesso | Igual: mesmo back-end, mesmas credenciais e mesmos campos. |
Classes bpmpi_* de dados de pedido, cartão, cobrança, entrega, aérea, recorrência e Merchant Defined Data (MDD), descritas em Mapear as classes | Iguais, inclusive as coleções com índice, como bpmpi_cart_1_name. |
Funções bpmpi_load(), bpmpi_authenticate() e BP.Mpi, com a chamada de bpmpi_authenticate() descrita em Implementar chamada ao evento de autenticação | Mesma assinatura e mesmo momento de chamada. |
bpmpi_config(), descrita em Parâmetros de entrada | Mesmos campos: Environment, Debug e callbacks. |
Callbacks onReady, onSuccess, onFailure, onUnenrolled, onUnsupportedBrand, onDisabled, onChallengeSuppression e onError, descritos em Eventos e Saídas | Mesmos nomes e mesmos campos (Cavv, Xid, Eci, Version, ReferenceId, ReturnCode e ReturnMessage). |
bpmpi_auth=false, bpmpi_auth_suppresschallenge e bpmpi_auth_notifyonly (Data Only), descritos em Acesso e tipo de autenticação e Data Only – somente notificação | Mesmo comportamento. |
| Desafio do emissor | Aparece na própria página, como hoje. |
Autorização com Payment.ExternalAuthentication, inclusive com Silent Order Post, descrita em Autorização com autenticação e Integração entre os scripts de autenticação 3DS e Silent Order Post (SOP) | Igual: o callback final traz os mesmos dados. |
Modo Debug, descrito em Parâmetros de entrada | Continua disponível em Sandbox, mas passa a registrar apenas mensagens de andamento, sem token, número de cartão ou dados de autenticação. Em Produção, é ignorado. |
Comportamentos novos
Limite do token e erros no onError
O MPI 2.1 limita cada token a apenas uma utilização. No caso de recusa da autenticação 3DS, o resultado será exibido no callback onError, com ReturnCode MPI900 e o motivo em ReturnMessage. A tabela a seguir mostra cada situação, a mensagem recebida e o que fazer:
| Situação | ReturnMessage recebido | O que fazer |
|---|---|---|
| O token já foi usado em dez inicializações. | An error has occurred (401) - Access token is no longer valid. Request a new token. | Recarregue o checkout com um token novo. |
| Houve muitas tentativas com cartões diferentes, segundo o controle de velocidade da Cielo. | An error has occurred (429) - Rejected by velocity check. | Trate como autenticação não concluída e não repita automaticamente. |
| O iframe do MPI não carregou em 15 segundos (CSP, rede ou bloqueador). | An error has occurred (0) - MPI bridge unavailable | Confira a CSP e a conectividade com o host do MPI. |
O navegador não tem suporte a MessageChannel. | An error has occurred (0) - Browser not supported | Os navegadores atuais têm suporte. Oriente a atualização do navegador. |
Há um limite de até dez inicializações por token. Quando o checkout gera um token por carregamento, o limite não será atingido.
Para a lista geral de códigos, consulte Códigos de retorno 3DS.
Recusa de chamadas do script antigo
Depois de confirmar que a integração da sua loja chega pelo MPI v2.1, as chamadas feitas pelo script antigo (BP.Mpi.3ds20.js, inclusive cópias hospedadas no seu servidor) são recusadas com "An error has occurred" (401) no onError. A partir daí, apenas o BP.Mpi.3ds21.min.js irá rodar a autenticação 3DS.
Roteiro de testes em Sandbox
Antes de publicar em Produção, rode cada cenário a seguir com Environment = "SDB" e com os cartões de teste para a autenticação 3DS. A tabela mostra o callback esperado em cada cenário:
| Cenário | Resultado esperado |
|---|---|
| Carregamento do checkout. | onReady |
| Autenticação sem desafio (frictionless). | onSuccess com Cavv, Xid, Eci e Version. |
| Autenticação com desafio. | O modal do emissor abre na página e, ao concluir, chega onSuccess. |
| Desafio com falha. | onFailure |
| Cartão não elegível. | onUnenrolled |
| Bandeira não suportada. | onUnsupportedBrand |
bpmpi_auth_suppresschallenge como true. | onChallengeSuppression |
bpmpi_auth como false. | onDisabled |
Faça também as verificações a seguir:
- Teste o Data Only (
bpmpi_auth_notifyonly), se você usa; - Autorize o pagamento com os dados do callback em
Payment.ExternalAuthentication(e via Silent Order Post, se você usa); - Troque de cartão depois de uma recusa, sem recarregar a página;
- Com a CSP de Produção ativa, confirme que não há bloqueio de
frame-srcno console do navegador; - No DevTools, confirme que as chamadas a
/v2.1/3ds/saem do iframe do MPI e que o campobpmpi_accesstokensome da página.
Dúvidas frequentes
Preciso mudar o back-end para usar o MPI v2.1?
Não. No MPI 2.1, a geração do token e a autorização continuam iguais às do MPI v2.
Posso hospedar o script do MPI v2.1 no meu servidor?
Não é recomendado. Carregue sempre o script do host do MPI, para receber as correções sem nova publicação.
O iframe do MPI v2.1 aparece para a pessoa compradora?
Não. O iframe fica oculto e só faz as chamadas ao MPI. O desafio do emissor continua no modal da própria página.
O MPI v2.1 funciona em página HTTP?
Não. O checkout precisa estar em HTTPS.
Quais ambientes existem para o MPI v2.1?
Apenas SDB (Sandbox) e PRD (Produção).
Posso usar o MPI v2.1 dentro de um app (WebView)?
Sim, se a WebView executar JavaScript e permitir iframes do host do MPI.
E se a pessoa compradora recarregar o checkout?
Gere um access_token novo a cada carregamento do checkout, inclusive quando a pessoa compradora recarrega a página.
Updated about 4 hours ago