Migração de gateway: checklist técnico para trocar de processador sem perder vendas

Imagine a seguinte cena: sua equipe de engenharia vira a chave para o novo gateway de pagamentos numa terça-feira à noite. O deploy foi um sucesso. Os logs estão limpos. Você vai dormir tranquilo. Na quarta-feira de manhã, o dashboard de vendas mostra uma queda de 22% na taxa de aprovação. O time de atendimento está soterrado de clientes reclamando que o cartão de crédito foi recusado. O antifraude está bloqueando transações legítimas. Você acabou de queimar milhares de reais em poucas horas.

Se você opera um e-commerce, uma plataforma SaaS ou um marketplace de alto volume, preste atenção aqui. O botão de "virar a chave" é o maior mito do mercado de pagamentos brasileiro.

Trocar de processador de pagamentos — seja saindo de um player legado para uma Adyen, ou migrando do Pagar.me para a Stripe ou Mercado Pago em busca de taxas melhores — é uma cirurgia de coração aberto na sua operação financeira. Nós acompanhamos dezenas de operações de grande porte derreterem margens de lucro por subestimarem a complexidade técnica dessa transação.

O mercado hoje não perdoa fricção no checkout. Um milissegundo de lentidão ou um falso positivo no antifraude joga seu cliente direto para o concorrente. Para garantir que sua empresa mude de provedor sem sangrar receita, desenhamos o checklist técnico definitivo. Nada de teorias. Apenas a engenharia de trincheira necessária para uma migração silenciosa e lucrativa.

A Ilusão do "Plug and Play"

Quinze anos atrás, o mercado brasileiro era um duopólio engessado entre Cielo e Rede. Hoje, temos um ecossistema vibrante de PSPs (Payment Service Providers), gateways e orquestradores. A promessa comercial é sempre a mesma: "nossa API é moderna, documentada e você integra em uma semana".

A API pode até ser simples. O problema mora no legado que você precisa carregar.

Quando você processa pagamentos há anos, seu banco de dados não guarda números de cartão de crédito. Ele guarda tokens. Esses tokens são chaves criptográficas amarradas ao cofre PCI-DSS do seu gateway atual. O gateway antigo não vai fácilitar a sua saída. Ele sabe que a posse dos cartões salvos (o famoso "comprar com um clique") é a maior barreira de retenção que existe.

Além disso, cada adquirente tem um apetite de risco diferente, rotas de adquirência diferentes e formas distintas de interpretar os códigos de erro (retries) devolvidos pelos bancos emissores (Itaú, Bradesco, Nubank, etc.). Uma transação que passava lisa no gateway A pode ser classificada como "Suspeita de Fraude" (Código 59) no gateway B simplesmente porque o payload de dados enviado ao emissor foi formatado de um jeito sútilmente diferente.

Fase 1: O Purgatório da Portabilidade de Tokens

A regra de ouro da migração: quem domina o cofre, domina o cliente. Se você tem assinaturas ativas (recorrência) ou clientes que compram frequentemente com cartão salvo, a migração de tokens é o seu primeiro e maior obstáculo.

O Padrão de Segurança de Dados da Indústria de Cartões de Pagamento (PCI-DSS) proíbe categoricamente que sua empresa manipule o PAN (Primary Account Number) em texto claro, a menos que você gaste alguns milhões de reais para certificar seus próprios servidores.

Na prática, a transferência de cartões ocorre diretamente entre os cofres do gateway antigo e do novo gateway. Como isso funciona?

1. O gateway novo gera um par de chaves criptográficas (PGP).
2. A chave pública é enviada ao gateway antigo.
3. O gateway antigo exporta os dados dos cartões (PAN, validade, nome), criptografa com essa chave pública e envia o arquivo via protocolo seguro (geralmente um servidor SFTP) para o gateway novo.
4. O gateway novo descriptografa com sua chave privada, insere no próprio cofre e devolve para você uma tabela de "De / Para" (Token Antigo -> Token Novo).

Network Tokens: O Jogo Mudou

Agora em 2024 e 2025, observamos a ascensão dos Network Tokens (bandeiras como Mastercard MDES e Visa VTS). Se o seu gateway antigo já útilizava tokens de bandeira em vez de tokens proprietários, a migração é drasticamente mais fácil e segura.

Os Network Tokens são agnósticos ao gateway. Eles acompanham o ciclo de vida do cartão do cliente (se o cartão expirar, a bandeira atualiza o token automaticamente). Exija que seu novo provedor suporte Network Tokenization nativamente. Isso blinda sua operação contra futuras migrações.

Fase 2: A Engenharia de Dual-Running

Nunca, sob nenhuma hipótese, desligue o gateway antigo no dia 1. A arquitetura correta exige um período de Dual-Running (ou Shadow Mode), onde ambos os sistemas operam simultaneamente em produção.

Para isso, você precisa de um roteador de pagamentos (um gateway interno seu, ou um orquestrador de mercado como Yuno ou Primer). O fluxo deve seguir a lógica de Canary Release.

O Cronograma de Tráfego

Recomendamos a seguinte rampa de aceleração para o novo processador:

• Semana 1 (95% Antigo / 5% Novo): Roteie apenas transações de baixo risco. Exemplo: compras de ticket médio baixo no PIX, ou novos cartões de crédito adicionados na plataforma. Monitore os webhooks de confirmação.
• Semana 2 (80% Antigo / 20% Novo): Comece a injetar os cartões migrados (tokens novos). Avalie a taxa de aprovação lado a lado. O novo gateway está aprovando tanto quanto o antigo?
• Semana 3 (50% / 50%): Teste de estrêsse. Aqui você avalia a estabilidade da API do novo parceiro em horários de pico (geralmente entre 19h e 22h).
• Semana 4 (10% Antigo / 90% Novo): O gateway antigo fica apenas como fallback (plano B). Se o novo gateway apresentar timeout de 3 segundos, a requisição é desviada para o antigo.

A Armadilha dos Soft Declines

Durante o Dual-Running, preste muita atenção aos códigos de recusa. Códigos como 51 (Saldo Insuficiente) são Hard Declines — o cliente realmente não tem dinheiro. Porém, se você notar um pico de erros genéricos como 05 (Transação não autorizada) ou 99 (Erro no sistema do banco), você está sofrendo Soft Declines.

Isso ocorre frequentemente porque o banco emissor ainda não "conhece" o seu novo gateway operando com o seu CNPJ. O algoritmo antifraude do Nubank ou do Itaú pode estranhar o novo padrão de requisições. O Dual-Running permite que os emissores calibrem seus modelos gradualmente, evitando bloqueios em massa.

Fase 3: Webhooks, PIX e o Inferno da Conciliação

Vender é apenas metade do trabalho. A outra metade é garantir que o dinheiro caia na conta correta e que o status do pedido seja atualizado no seu ERP.

Na transição de gateways, os payloads (formatos de dados) dos Webhooks (notificações assíncronas) mudam completamente. Um erro clássico de migração é esquecer de mapear todos os status possíveis.

O gateway antigo chamava o status de "paid". O novo chama de "authorized" e só depois muda para "captured". Se o seu sistema não entender a diferença, você pode acabar despachando mercadorias que foram apenas autorizadas, mas não capturadas. O prejuízo é certo.

A Dinâmica do PIX

Com o PIX representando mais de 40% do volume de transações no e-commerce brasileiro (segundo dados recentes do BACEN), a migração do fluxo de PIX exige atenção cirúrgica.

O PIX é síncrono para o cliente, mas muitos gateways o tratam de forma assíncrona via webhooks. Valide rigorosamente o tempo de resposta (SLA) do novo gateway para a confirmação do PIX. Se demorar mais de 5 segundos para o webhook chegar, seu cliente fecha a tela de checkout achando que deu erro, e o seu sistema de atendimento entra em colapso.

O Quebra-Cabeça da Conciliação

Se você usa conciliação automatizada (como Equals ou Vindi), precisará de novos layouts de arquivos de liquidação (EDI). Durante o período de Dual-Running, sua equipe financeira terá que conciliar dois relatórios distintos, com taxas de desconto (MDR) diferentes, datas de liquidação diferentes e regras de antecipação de recebíveis diferentes.

O Checklist Técnico Definitivo

Para fácilitar a vida do seu CTO e do seu time de Produto, consolidamos os passos inegociáveis. Imprima isso e cole na parede da sala de guerra da engenharia.

1. Preparação e Contratos

• O contrato com o gateway atual permite a exportação de tokens PCI?
• O novo gateway possui ambiente de sandbox com simuladores de erro (cartões que forçam erro de saldo, erro de fraude, etc.)?
• As chaves PGP foram geradas e testadas entre as duas adquirentes?

2. Integração e Antifraude

• O payload enviado para o antifraude (ClearSale, Konduto, Signifyd) foi atualizado para refletir o novo gateway?
• O device fingerprint (coleta de dados do navegador/celular do usuário) do novo gateway está implementado nas telas de front-end?
• Os fluxos de 3DS2 (autenticação com o banco emissor) estão abrindo corretamente no mobile e no desktop?

3. Operação e Fallback

• A infraestrutura de roteamento permite virar a porcentagem de tráfego (0 a 100%) sem necessidade de um novo deploy de código?
• Existe uma regra de retry configurada? (Ex: Se Gateway Novo = Timeout, tentar Gateway Antigo).
• O mapeamento de De/Para dos status de pedido (Autorizado, Capturado, Cancelado, Chargeback) está homologado no ERP?
• O time de Customer Success tem acesso a um dashboard unificado para buscar transações dos dois gateways durante a transição?

Implicações Práticas e Visão de Futuro

Trocar de gateway por uma diferença de 0.10% na taxa de MDR (Merchant Discount Rate) pode parecer um excelente negócio na planilha do CFO. Mas se a migração for mal executada e custar 5% da conversão de vendas ao longo de três meses, o ROI dessa troca será negativo por anos.

Observamos que as empresas mais maduras do Brasil abandonaram a ideia de ter um único provedor de pagamentos. O futuro (e o presente de quem opera em alta performance) é a multi-adquirência ativa.

Ao invés de migrar 100% do seu volume de um player para outro, a estratégia mais inteligente é adicionar o novo player à sua esteira, manter o antigo como backup e usar inteligência de roteamento para decidir, transação a transação, quem tem a maior probabilidade de aprovar aquele cartão específico, pelo menor custo.

Migrar um gateway não é um projeto de TI. É um projeto de continuidade de negócios. Traté os tokens de cartão dos seus clientes com o mesmo rigor que você trata o caixa da empresa — porque, no fundo, eles são exatamente a mesma coisa.