Migrar de gateway de pagamento: como trazer lojistas

Migrar um lojista de outro gateway para a sua operação é trocar a porta de entrada do dinheiro sem fechar a antiga de uma vez. O lojista refaz o cadastro e o KYC/KYB com você, troca as chaves de API, o checkout e os webhooks, e os dois gateways rodam em paralelo até o novo fluxo estar provado. Tudo o que aconteceu antes da troca fica no gateway anterior: saldo, reservas, repasses agendados e as contestações das vendas antigas.

O que fica e o que vem

Mostre essa tabela ao lojista antes de começar. Assim ele não entra na migração esperando ver o saldo antigo no painel novo.

1. Mapeie a base

Antes de chamar o primeiro lojista, levante, para cada um:

• como vende: integração própria por API, checkout externo, links de pagamento ou mais de um;
• o volume e os meios de pagamento: quem depende de cartão precisa saber que, na plataforma, cartão depende do provedor, da integração e da homologação;
• quem cuida da integração: o próprio lojista, uma agência ou um desenvolvedor contratado;
• o contrato atual: aviso prévio, multa, prazo de reserva e regras de saída.

Comece pelos lojistas com integração simples e volume médio. Deixe os maiores para depois do piloto.

2. Cadastro e KYC/KYB de novo

A aprovação no gateway antigo não vale na sua operação. Você responde pelo seu cadastro e precisa dos seus critérios, escritos na política de aceitação de lojistas. O lojista envia os documentos pelo painel, e a sua equipe aprova, reprova ou pede complementação. A lista de documentos e o que acontece com contas pendentes estão em KYC/KYB na plataforma.

Uma conta em análise não faz cobranças reais, mas o lojista não fica parado: a chave de teste pode ser criada antes da aprovação. Assim, a integração e o cadastro andam ao mesmo tempo.

3. Integração e checkout

Do lado técnico, a troca tem três partes:

1. API. O sistema do lojista passa a chamar a API da sua operação, no seu domínio, com as chaves novas. Os valores trafegam em centavos, e a criação de cobranças e de saques aceita chave de idempotência. Os nomes de campos e de status podem ser diferentes dos do gateway antigo, então a integração precisa ser revisada, não só a URL.
2. Checkout externo. Se o lojista vende por uma plataforma de checkout, como Vega ou Zeedy, a sua operação se conecta a ela. Combine com o lojista o momento da troca dentro da ferramenta.
3. Links de pagamento. Os links e QR Codes antigos continuam apontando para o outro gateway. Crie os novos no painel e troque em todos os lugares onde estão publicados: site, redes sociais, mensagens automáticas e campanhas.

Teste tudo com as chaves de teste: o endpoint de simulação marca a cobrança como paga e dispara o webhook, sem mover dinheiro.

4. Webhooks

O webhook merece atenção própria, porque o pedido só dá baixa quando o aviso chega e é entendido.

• Cadastre o novo endpoint e confira a assinatura de cada envio com o segredo novo.
• Durante o paralelo, o sistema do lojista recebe avisos dos dois gateways. Ele precisa distinguir a origem e mapear os status de cada um.
• Processe cada evento uma vez só. A plataforma reenvia quando não recebe confirmação, então o sistema do lojista deve ignorar o aviso repetido.
• Não desligue o endpoint antigo enquanto houver cobrança aberta, estorno ou contestação lá.

Quando algo não bate, o identificador de cada requisição leva à chamada na tela de logs da API, com status, duração e código de erro.

5. Saldo, reservas e repasses no gateway antigo

O dinheiro que já entrou no gateway antigo é responsabilidade dele, conforme o contrato com o lojista. A sua operação não move esse saldo. Na prática:

• o lojista saca o saldo disponível pelas regras de lá;
• a reserva pode continuar retida pelo prazo que o contrato antigo prevê para contestações;
• repasses agendados seguem o calendário antigo;
• durante a transição, o lojista tem dinheiro em dois lugares, e o fluxo de caixa dele precisa contar com isso.

Não prometa antecipar ou cobrir valores presos no outro gateway. Esse é um compromisso financeiro que a sua operação não controla.

6. MED e chargeback das vendas antigas

As contestações chegam depois da venda, e a troca de gateway não as cancela.

No Pix. O MED é tratado na conta que recebeu o Pix original. Pelo regulamento do Pix, anexo à Resolução BCB 1/2020, as devoluções devem ser iniciadas em até 90 dias da transação original (art. 41-A, II). Uma venda feita no gateway antigo na véspera da troca ainda pode gerar bloqueio e devolução lá, com o saldo de lá. Se o lojista zerou a conta antiga, o gateway anterior vai cobrar o que o contrato prevê. O processo completo está em MED para gateway de pagamento.

No cartão. O chargeback segue as regras de cada arranjo. A Resolução BCB 522 exige que essas regras limitem a responsabilidade financeira dos participantes às contestações iniciadas até 180 dias da autorização da transação. Esse limite vale entre os participantes do arranjo; o que o lojista deve ao gateway antigo é o que o contrato entre eles diz. Os demais pontos da norma estão em Resolução BCB 522 e a gestão de riscos.

7. Comunicação

Um bom roteiro para o lojista responde a cinco perguntas:

1. O que muda e a partir de quando.
2. O que ele precisa fazer: documentos, integração, troca de links.
3. O que fica no gateway antigo e até quando.
4. Quais taxas e prazos passam a valer, por escrito no contrato com o lojista.
5. Com quem ele fala se algo der errado durante a troca.

Lembre também o comprador final. Confirme com o parceiro financeiro como o recebedor aparece no aplicativo do pagador e no comprovante do Pix, e avise o lojista se isso mudar: um nome desconhecido no comprovante pode gerar desconfiança e contestação.

8. Paralelo e virada

1. Piloto. Comece com poucos lojistas e transações reais de baixo valor, do pagamento ao saque.
2. Critérios de virada. Por exemplo: cobranças pagas com baixa automática, o primeiro saque concluído e a conciliação batendo com o extrato.
3. Migração em blocos. Traga os próximos lojistas em grupos, com a mesma lista de verificação.
4. Desligamento. O lojista desliga o gateway antigo quando não houver cobrança aberta, repasse pendente nem contestação dentro do prazo.

Lojistas que migraram sem problema podem indicar os próximos. As outras frentes de aquisição estão em como conseguir os primeiros lojistas.

Onde a XF TECH entra

A plataforma da XF TECH dá à sua operação o que a migração usa: KYC/KYB no painel, chave de teste antes da aprovação, endpoint de simulação, webhooks assinados com reenvio, logs de requisições, links de pagamento, integração com checkouts externos, reservas e acompanhamento de disputas, chargebacks e MED. Ela não transfere saldo do gateway antigo nem substitui o contrato que o lojista tem com ele.

Conteúdo informativo, atualizado em 25/10/2026. Não substitui orientação jurídica.