Se você já tem assinaturas ativas, elas podem entrar na Chargefy com o período atual preservado. A Chargefy não cobra de novo o ciclo que o cliente já pagou; a próxima cobrança acontece na data real da renovação.
O que entra na migração
O que você configura na virada
E as vendas antigas?
Hoje a Chargefy não oferece importação de vendas e pagamentos já processados em outro sistema. Na prática, isso significa:- vendas antigas continuam como histórico no sistema de origem;
- a Chargefy começa a registrar vendas novas quando você cria checkout sessions, payment links, payment intents ou quando uma assinatura renovada gera a próxima cobrança;
- para conciliar a migração, guarde IDs da origem em
metadatanos customers, assinaturas e recursos que você criar daqui para frente.
Escolha seu caminho
Importar assinaturas
Traga assinaturas ativas, em trial ou já canceladas, preservando datas e evitando cobrança duplicada.
Criar checkout novo
Comece a criar novas vendas na Chargefy com pagamento único ou assinatura.
Coletar cartão depois
Salve um cartão para cobranças futuras sem que o número do cartão toque o seu backend.
Dar autonomia ao cliente
Use o portal hospedado para troca de cartão, dados de cobrança, faturas e ações em assinaturas.
Migrar uma plataforma
Crie organizações conectadas, faça a ativação financeira e use cada
org_* na URL ou no header, conforme o recurso.Evitar duplicidade em lote
Use
Idempotency-Key para repetir uma importação com segurança quando houver retry ou falha de rede.Roteiro recomendado
1
Mapeie os IDs do sistema atual
Antes de importar, escolha quais IDs você vai guardar para reconciliação: cliente, assinatura, plano, pedido ou conta. Coloque esses valores em
metadata para encontrar tudo depois.2
Crie os clientes
Cada cobrança e assinatura pertence a um customer. Traga primeiro os dados básicos de identificação e cobrança dos seus clientes.
3
Recrie o catálogo essencial
Cadastre produtos e preços quando você tem planos reutilizáveis. Para casos sob medida, você também pode informar o preço direto na criação da cobrança ou assinatura.
4
Importe as assinaturas que já existem
Para assinaturas em andamento, informe quando o período atual começou e quando será a próxima cobrança. Assim a Chargefy sabe que o ciclo atual já foi pago no sistema de origem.
5
Colete cartões sem travar a migração
Você não precisa ter o cartão de todos os clientes no primeiro dia. Uma assinatura pode ser importada sem cartão; antes da próxima cobrança, envie o cliente para o portal ou para um fluxo de tokenização.
6
Vire o tráfego novo para a Chargefy
Depois de validar clientes, catálogo, webhooks e cobranças de teste, passe novas vendas, renovações e alterações de plano para a Chargefy. A partir desse ponto, o histórico novo nasce aqui.
Cuidados importantes
- Não cobre o período atual duas vezes. Use o fluxo de importação de assinaturas para preservar as datas reais.
- Use uma chave de idempotência por item importado. Se a importação for repetida, a mesma operação não cria duplicatas.
- Planeje a coleta de cartão antes da próxima renovação. Isso reduz faturas em aberto e pedidos de suporte.
- Configure webhooks desde o começo. Eles são a fonte confiável para saber quando uma cobrança criada na Chargefy foi paga, falhou, expirou ou quando uma assinatura mudou.
- Não planeje importar histórico de vendas antigas como pagamentos da Chargefy. Use o sistema de origem para consulta histórica e a Chargefy para o ciclo novo.
- Valide tudo primeiro em um ambiente controlado da sua aplicação antes de apontar tráfego de produção.
Próximos passos
Guia de importação de assinaturas
Passo a passo para trazer assinaturas ativas, em trial ou canceladas.
Criar customer
Contrato para criar clientes pela API.
Criar produto
Cadastre o que você vende.
Criar preço
Defina valores avulsos ou recorrentes.