Paybyrd Paybyrd
Registo gratuito
O playbook de migração · edição 2026

Como deixar o seu processador actual sem partir os pagamentos.

Um runbook de 47 pontos escrito pelos engenheiros que migraram a TAP Air Portugal, a Vila Galé, a Prozis e a KuantoKusta. Framework faseado, checklists técnica e comercial, red flags honestos. Escrito como se estivéssemos a fazer o briefing da nossa própria equipa — não é um pitch comercial.

Quer o runbook completo na sua caixa de entrada? Um email com todas as secções em cima, mais os links para a sua equipa colar no Confluence / Notion.

Sem lista de marketing. Um email com o runbook + um follow-up 14 dias depois para ver como correu.

O que está dentro
  1. 01Porque falham as migrações
  2. 02O framework em 5 fases
  3. 03Checklist técnica de migração
  4. 04Checklist comercial
  5. 05Perguntas a fazer antes de dizer que vai sair
  6. 06Quando NÃO trocar
  7. 0722 dias até tráfego real · Vila Galé
  8. 0830-60-90 pós-migração
01 · Porque falham as migrações

Quase nunca é a integração.

Fizemos o diff de dezenas de migrações — nossas e da concorrência. Quando uma descarrila, a causa-raiz está quase sempre nos mesmos cinco sítios. Conhecê-los à partida transforma um projecto arriscado de 60 dias num projecto aborrecido de 22.

  1. 01

    O cutover tudo-ou-nada

    A equipa vira 100% do tráfego na segunda de manhã. Às 11 de terça, o diff revela falhas de re-auth em subscrições que ninguém apanhou em sandbox. Fazer rollback agora significa virar o tráfego outra vez, re-disparar os mesmos failure modes na direcção inversa. Migre sempre por processamento paralelo com rampa faseada — 5% → 20% → 50% → 100% ao longo de 2–4 semanas.

  2. 02

    Re-auth de tokens de cartão à escala

    Tem 80 000 clientes com cartões guardados. O novo processador não suporta a importação de network tokens do seu fornecedor actual. Resultado: 80 000 emails de re-autenticação em duas semanas, centenas de clientes perdidos entre shoppers mais velhos confundidos, e a equipa de CS afogada em tickets. Verifique sempre a portabilidade dos network tokens antes de assinar.

  3. 03

    Drift de reconciliação durante a passagem

    O processador actual paga a T+2. O novo paga a T+1. Durante o processamento paralelo, a sua equipa de finanças reconcilia duas cadências contra um só ERP. Um pagamento aparece no mês errado, um refund aparece duas vezes, e o CFO perde a confiança nos números durante todo o trimestre. Alinhe o mapeamento do livro-razão ANTES de virar qualquer tráfego.

  4. 04

    Mismatches nos webhook endpoints

    O processador antigo dispara payment.captured. O novo dispara transaction.succeeded. Isolados, ambos parecem correctos. Juntos, contornam a sua lógica de fulfillment — os pagamentos processam-se bem, mas nada é despachado. Coloque novos handlers de webhook a par dos antigos antes de virar uma única transacção, e faça replay de eventos históricos contra eles durante uma semana.

  5. 05

    Documentação PCI em falta

    O novo processador usa um padrão diferente de componente embebido. O auditor do seu cliente pede um SAQ actualizado. Passam oito semanas. Entretanto não pode mexer na página de checkout sem voltar a definir o âmbito. Obtenha a Attestation of Compliance (AoC) + o tipo de SAQ do novo processador por escrito ainda na avaliação — não depois do go-live.

Quer isto como um doc de runbook editável?

Deixe o seu email — enviamos o playbook completo num só email que a sua equipa pode arquivar, mais um toque 14 dias depois para ver como vai o planeamento da migração.

↓ Ou continue a ler — o playbook completo está abaixo, organizado por secção.

02 · O framework em 5 fases

Do contrato aos 100% de tráfego real, em cinco fases.

Publicamos estes prazos como valores por omissão. Para a maioria dos comerciantes abaixo de €500M de volume anual, este framework entra em produção de forma limpa em 20–28 dias úteis sem disrupção visível para o cliente. Contas enterprise com stacks de reconciliação complexas podem adicionar 2–4 semanas.

  1. Fase 0 · Pré-trabalho
    Semana 0
    Alinhamento de stakeholders

    Nomear o dono em ambos os lados. Confirmar que o CFO assinou em baixo o custo do processamento paralelo. Congelar o backlog de funcionalidades durante a janela de migração.

  2. Fase 1 · Onboard
    Semana 1–2
    Sandbox + integração

    Certificar o sandbox. Colocar webhook endpoints paralelos. Exportar o histórico. Testar 10 tokens reais end-to-end.

  3. Fase 2 · Paralelo
    Semana 3–4
    5–20% de tráfego real

    Transacções marcadas correm pelos dois lados. Relatório de diff diário. As finanças validam um ciclo de pagamentos antes de expandir.

  4. Fase 3 · Rampa
    Semana 5–6
    Cutover gradual

    20% → 50% → 80% → 100%. O interruptor de rollback é seu. Os SREs da Paybyrd estão no seu canal Slack em cada subida.

  5. Fase 4 · Validação
    Semana 7–8
    Sunset + estabilização

    Fechar o processador antigo a novo volume. Calendarizar a libertação de reservas. Mapear o ownership da cauda de chargebacks. Plano 30-60-90 armado.

03 · Checklist técnica de migração

A passagem técnica de 36 pontos.

Trabalhe cada item antes da Fase 2. Risque o que não se aplica à sua stack (ex.: sem subscrições = saltar o grupo de tokenização). O resto não é negociável.

Superfície de integração

4 pontos
  • Inventariar todos os codepaths que chamam o processador actual (checkout, subscrições, refunds, ferramentas internas, exports de reporting, painéis de customer service).
  • Identificar as versões dos SDK em produção — alguns endpoints estão presos à versão; o novo processador pode precisar de versões equivalentes ou de uma lib paralela.
  • Documentar os webhook handlers existentes e as suas garantias de idempotência antes de tocar em seja o que for.
  • Catalogar cada cartão de teste / conta de teste hard-coded. Não vão funcionar do novo lado.

Passagem de dados

5 pontos
  • Exportar o histórico completo de transacções (no mínimo 18 meses) em CSV e no formato nativo do processador. Vai precisar disto para refunds, chargebacks e auditorias fiscais durante muito tempo depois do cutover.
  • Exportar todos os tokens de cartão guardados com os metadados de validade — vai referenciar isto ao importar para o vault do novo processador.
  • Exportar registos de clientes, agendas de subscrição, planos de pagamento e métodos de pagamento guardados.
  • Fazer snapshot do histórico de chargebacks (incluindo fases de arbitragem) — o novo processador herda as obrigações de disputa em casos em curso.
  • Preservar todos os documentos de atestação PCI. Os auditores vão pedir.

Tokenização e subscrições

4 pontos
  • Confirmar que o novo processador suporta a importação de network tokens do seu fornecedor actual (tokens Visa/Mastercard são portáveis; tokens proprietários específicos da marca muitas vezes não são).
  • Para subscrições: decidir a estratégia de re-auth. A portabilidade do network token evita re-auth visível para o cliente. Tokens proprietários implicam nova entrada na próxima cobrança — planear a comunicação.
  • Testar a migração numa amostra de 10 tokens reais end-to-end antes de migrar em massa.
  • Verificar os fluxos de step-up 3DS2 do novo lado para transacções recorrentes e iniciadas pelo comerciante.

Webhooks e assíncronos

4 pontos
  • Colocar os novos webhook endpoints a par dos existentes; não substituir até o processamento paralelo validar paridade.
  • Testes de replay: o novo endpoint consegue lidar com a shape antiga do payload? (As suas ferramentas de backfill / reconciliação podem ainda enviar eventos legados durante semanas.)
  • Verificar que as idempotency keys funcionam de forma idêntica do novo lado. Double-capture / double-refund são os bugs clássicos de migração.
  • Confirmar que as políticas de retry dos webhooks são compatíveis com a sua tolerância a at-least-once existente.

Fraude e risco

4 pontos
  • Exportar as regras de fraude actuais (block lists, regras de velocidade, restrições geográficas) e traduzi-las para a gramática do novo motor — não copy-paste.
  • Correr shadow mode na nova stack de fraude durante 2–3 semanas antes de activar decisões.
  • Verificar que o fluxo de challenge 3DS2 do novo lado corresponde às expectativas dos clientes (mesma transição de UI, mesma UX de sucesso/falha).
  • Sincronizar BIN lists, regras ao nível do emissor e lógica específica de bandeira.

Reconciliação e finanças

4 pontos
  • Mapear a nova cadência de pagamentos contra o seu livro-razão / ERP existente. Diferenças T+0 / T+1 / T+2 partem a reconciliação automatizada em silêncio.
  • Confirmar que o detalhe por loja / SKU / canal disponível no novo lado iguala (ou supera) os seus relatórios operacionais actuais.
  • Alinhar as datas de fim de mês entre o antigo e o novo para que as finanças possam fechar livros sem double-counting.
  • Marcar as transacções processadas em paralelo nos dois lados com um identificador partilhado (a sua order ref é ideal) para relatórios de diff automatizados.
04 · Checklist comercial

Antes da equipa jurídica tocar no contrato novo.

A engenharia leva os holofotes; é o procurement que decide se a migração se paga de facto. Estes três grupos são os que o seu CFO precisa de ter respondidos antes de assinar.

Termos de saída com o processador actual

3 pontos
  • Ler o contrato. Período de aviso, taxas de saída, obrigações de exportação de dados, tratamento da cauda de chargebacks, calendário de libertação de reservas.
  • Confirmar que a data da sua última transacção de novo volume NÃO desencadeia penalizações por rescisão antecipada.
  • Se o processador actual oferecer algum incentivo para ficar, obtê-lo por escrito e avaliá-lo contra o valor total da migração.

Acordos com adquirentes / schemes

3 pontos
  • Se tiver contratos directos com adquirentes separados, não precisa de os mover — a maioria dos orquestradores (Paybyrd incluída) fica por cima.
  • Negociar com o novo processador se vai consolidar acquiring ou manter os seus acordos existentes.
  • Rever termos de interchange++ com atenção; preços mistos e IC++ têm implicações de cash-flow muito diferentes à escala.

Reservas e retenções

3 pontos
  • Obter compromissos por escrito sobre quando as reservas retidas serão libertadas após a migração (o padrão é 180 dias após a última transacção de novo volume).
  • Confirmar o ownership da cauda de chargebacks: o processador actual continua responsável por disputas levantadas sobre transacções pré-migração.
  • Partilha de receita de surcharge e DCC — perceber ambos os lados antes de virar.
05 · Perguntas a fazer antes de dizer que vai sair

A prioridade de suporte cai no momento em que anuncia.

Faça o trabalho de exportação e libertação de reservas antes da conversa. Assim que o aviso estiver apresentado, o incentivo do processador actual para o ajudar a exportar de forma limpa é zero. A sequência importa.

  1. 01 Posso exportar 24 meses de histórico de transacções no formato nativo deles E em CSV standard, hoje, sem assistência?
  2. 02 A portabilidade de network tokens funciona para a nossa base de cartões Visa + Mastercard guardados? (Resposta: sim, sempre — mas confirme por escrito.)
  3. 03 Quando é libertada a retenção de reservas e qual é o calendário? (Padrão: 180 dias após a última transacção de novo volume.)
  4. 04 Quem é responsável pelos chargebacks e disputas levantados após a migração contra transacções pré-migração? (Resposta: o processador antigo, mas documente-o.)
  5. 05 Qual é a cadência de notificação de disputas após a nossa conta ser fechada a novo volume? (Alguns caem para batches mensais — brutal para SLAs de resposta.)
  6. 06 Perdemos acesso ao dashboard de admin imediatamente na migração, ou há um período em read-only? (Peça 180 dias; muitos concedem 90.)
  7. 07 Há alguma cláusula de volume mínimo que desencadeie penalizações se reduzirmos durante o processamento paralelo?
  8. 08 Para negócios de subscrição: o acordo de recorrência transfere-se automaticamente com a portabilidade de network tokens, ou devemos avisos de re-auth aos clientes?
06 · Quando NÃO trocar

Dizemos-lhe quando é má ideia.

Nem todo o trimestre é bom trimestre de migração. Aqui ficam as cinco situações onde a resposta honesta é "espere" — mesmo que esteja certo de que os novos números são melhores.

Entra em época alta a < 8 semanas.

Até uma migração limpa de 22 dias tem rabo operacional. Não migre para dentro da Black Friday / Natal / pico turístico de Verão. Planeie o cutover para a sua janela mais calma de seis semanas.

A sua equipa técnica são um ou dois engenheiros.

O processamento paralelo exige monitorizar os dois lados em simultâneo. Se não tem bandwidth, negoceie mais apoio de migração com o novo processador ou faseie o projecto por 3+ meses.

Ainda não exportou tudo.

O dia em que anuncia a mudança é o dia em que a prioridade de suporte do processador actual cai. Faça primeiro os exports, assine depois.

O seu checkout é muito customizado sem cobertura de testes.

O processamento paralelo é como descobre os mismatches. Se não consegue instrumentar os dois lados com relatórios de diff, está a voar às cegas.

O seu contrato tem um surcharge variável que dispara com quebras de volume.

O processamento paralelo vai dividir brevemente o seu volume. Leia as letras pequenas — alguns contratos penalizam isto.

07 · A migração de 22 dias · Vila Galé

Contrato na segunda. Tráfego real três semanas depois.

A Vila Galé tem 40+ hotéis em Portugal e no Brasil com um motor de reservas unificado, POS on-property e um canal mobile a crescer. A migração deles do processador anterior para a Paybyrd foi a migração hospitalidade enterprise mais rápida que corremos — aqui está como foi mesmo o cronograma.

Hotéis migrados
40+
Canais unificados
Web + POS + Quiosque
Do contrato ao ar
22 dias
Disrupção para o cliente
Zero
  1. Dia 1 · Contrato assinado

    Equipa de integrações emparelhada. Credenciais de sandbox entregues dentro de 4 horas. 18 meses de histórico de transacções exportados do lado antigo até ao Dia 3.

  2. Dia 4–9 · Endpoints paralelos em pé

    Novos webhook listeners implantados a par dos antigos. Portabilidade de network tokens para 200K cartões guardados validada numa amostra de 50 linhas. Sandbox certificado contra o fluxo de reservas de staging real.

  3. Dia 10–14 · 5% de tráfego real

    A Paybyrd processou 1 em cada 20 transacções reais durante 5 dias. Relatório de diff a correr todas as manhãs. Única anomalia: um drift de arredondamento na taxa turística, apanhado em menos de 24 horas. Corrigido no Dia 11.

  4. Dia 15–19 · 20% → 50% → 80%

    Subidas graduais. A equipa de finanças correu o fecho de mês sobre volume processado em paralelo — a reconciliação bateu certa até 4 cêntimos em €3,2M de receita reservada.

  5. Dia 20–22 · Cutover a 100%

    Processador antigo fechado a novo volume no Dia 20. Libertação de reservas a 30 dias calendarizada. SRE on-call da Paybyrd sentado no Slack deles durante a primeira semana pós-cutover. Zero incidentes visíveis para o cliente.

"As finanças fecham o dia em horas, não em segundas-feiras. A migração em si foi menos disruptiva do que uma semana normal de release."

— Vila Galé, retrospectiva pós-migração
08 · 30-60-90 pós-migração

As três janelas onde ainda importa.

O cutover não é a meta. A maior parte das migrações que "foram ao ar limpas" continua a perder valor por duas razões: a passagem da cauda de chargebacks vai à deriva, e a paridade da taxa de aprovação não é validada contra a nova baseline.

Dia 0 – 30

Estabilizar

  • • Diff diário de taxa de aprovação contra a baseline antiga.
  • • Auditoria semanal de reconciliação (primeiro ciclo de pagamentos).
  • • Drift de volume de tickets de customer service monitorizado. (Pico = alguma coisa escapou aos relatórios de diff.)
  • • Canal de notificação da cauda de chargebacks do processador antigo confirmado a funcionar.
Dia 30 – 60

Optimizar

  • • Afinar o routing multi-adquirente contra os seus padrões reais de recusa.
  • • Activar decisões de fraude depois de 3 semanas de observação em shadow mode.
  • • Primeiro mês calendário completo de reporting — revisão do CFO.
  • • Libertação de reservas agendada, 180 dias desde a última transacção.
Dia 60 – 90

Validar o business case

  • • Custo misto por transacção vs a baseline antiga — a poupança real bate a projecção?
  • • O ganho de aprovações materializou-se?
  • • Volume de tickets de suporte em paridade ou melhor?
  • • Novas capacidades activadas (partilha de receita DCC, InstaTax, customer intelligence, etc.) — já geraram receita?

Ainda aqui? Ponha números contra isto.

30 minutos com um engenheiro de pagamentos sénior. Traga o seu extracto mais recente do processador. Vamos percorrer este framework contra o seu stack real, e sai com um plano de migração de 22 dias por escrito — mesmo que não vá com a Paybyrd.

Marcar 30 min com um engenheiro