Integração de Pagamentos via iFrame

Visão Geral

A Wake Commerce está migrando a integração de checkout para o modelo de pagamento via iFrame seguro. Esta atualização fortalece a segurança das transações e padroniza o fluxo de pagamento em toda a plataforma.

📘

Escopo desta versão

Neste primeiro momento, a migração se aplica exclusivamente a lojas que utilizam o Conector Wake Gateway como meio de pagamento.

Todos os parceiros e agências que desenvolveram integrações de pagamento personalizadas com o Wake Gateway precisam atualizar suas implementações seguindo as instruções deste documento antes da data limite de ativação.

🚧

Atenção — Ação Obrigatória

A ativação da nova estrutura de pagamento iFrame será realizada pela Wake Commerce. Após a ativação, integrações não migradas poderão apresentar falhas no checkout.

Realize os testes descritos neste documento e, quando ocorrer ativação pela Wake, sua loja já estará preparada.

O Que Muda na Integração

A principal mudança é que o formulário de pagamento passa a ser renderizado dentro de um iFrame isolado, substituindo o modelo de campos abertos no DOM da loja. Isso implica:

• A estilização (CSS) do checkout precisa ser adaptada para respeitar os limites do iFrame.

• Um arquivo CSS específico deve ser criado ou modificado conforme a versão do Storefront.

• O fluxo de ativação definitivo será definido via ticket ou pelo time de Customer Success da Wake — aguarde comunicado oficial.

Arquivo CSS de Estilização

O iFrame de pagamento utiliza um arquivo CSS dedicado para personalização visual. O nome e o local do arquivo variam conforme a versão do Storefront:

Crie ou edite esse arquivo para garantir que o formulário de pagamento seja exibido de forma consistente com o layout de cada loja.

Ambiente de Testes

Antes da ativação definitiva, é fundamental que cada agência valide a exibição do checkout e os ajustes de CSS necessários. O procedimento padrão é o mesmo para ambas as versões do Storefront.

Procedimento padrão — Storefront 1.0 e Storefront 2.0

Passo 1 — Acessar a página de checkout da loja

Abra a loja no navegador e navegue até a página de checkout.

Passo 2 — Adicionar o cookie de teste via console

Abra as ferramentas de desenvolvedor do navegador (F12) e acesse a aba Console. Execute o comando abaixo para habilitar o iFrame de pagamento apenas para a sua sessão:

document.cookie = "use-secure-gateway=true; path=/";

Recarregue a página após inserir o cookie. Após a seleção do meio de pagamento, o checkout deve passar a renderizar o formulário de pagamento via iFrame.

Passo 3 — Ajustar o arquivo CSS e validar

Com o iFrame visível, verifique a exibição do formulário e realize os ajustes necessários no arquivo secure-card.css. Repita até o layout estar correto.

Passo 4 — Remover o cookie após os testes

Ao finalizar, remova o cookie para retornar ao comportamento padrão da loja:

document.cookie = "use-secure-gateway=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;";

Caso o cookie não reflita no Storefront 2.0

Se, após inserir o cookie, o iFrame não for renderizado em uma loja Storefront 2.0, isso indica que os snippets nativos de renderização do formulário de pagamento foram customizados. Nesse caso, siga o procedimento abaixo para testar:

Passo 1 — Criar uma nova branch no repositório da loja

Crie uma branch específica para os testes do iFrame. Nunca altere a branch principal (main/master) durante esse processo.

Passo 2 — Localizar a query que renderiza o meio de pagamento selecionado

Dentro do repositório da loja, encontre a query responsável por renderizar o meio de pagamento selecionado no checkout.

Passo 3 — Forçar o parâmetro useSecureGateway

Na query localizada, adicione o parâmetro abaixo:

selectedPaymentMethod(useSecureGateway: true)

Isso forçará a renderização via iFrame exclusivamente nessa branch, permitindo visualizar e ajustar o CSS.

Passo 4 — Validar e descartar as alterações

Valide o layout com o iFrame ativo e finalize os ajustes no secure-card.css. Após a validação, descarte as alterações na query — somente o arquivo CSS deve ser mantido e publicado.

Resumo Comparativo por Versão

Fluxo de Ativação Definitiva

Após concluir os testes e ajustes de CSS, a ativação definitiva da integração iFrame na loja em produção será realizada pela Wake Commerce.

Boas Práticas e Recomendações

• Sempre realize os testes utilizando o cookie de sessão antes de qualquer alteração em produção.

• Documente as alterações de CSS realizadas em cada loja para facilitar futuras manutenções.

• Ao usar o fluxo alternativo com branch, nunca faça commit do parâmetro useSecureGateway: true na query — apenas o CSS deve ser publicado.

• Em caso de dúvidas durante os testes, entre em contato com o time técnico da Wake antes de avançar.

• Valide o fluxo completo de checkout (inserção de dados, confirmação e retorno pós-pagamento) durante os testes.

Suporte e Contato