Auto Top-Up via cartão tokenizado

Auto Top-Up evita que sua aplicação caia por saldo zerado. Tokia monitora saldo continuamente e quando passa do threshold, faz cobrança automática via cartão tokenizado.

Pré-requisito

CPF/CNPJ cadastrado em /dashboard (LGPD + emissão de NF). Sem isso, cadastro de cartão é bloqueado.

Passo 1 — Acesse /dashboard/billing

Você vê 2 seções:

• Métodos de pagamento: cartões salvos (vazio se primeira vez)
• Auto Top-Up: configuração de recarga automática (desativado por default)

Passo 2 — Cadastrar cartão

Clica "Adicionar cartão". Formulário aparece pedindo:

• Número do cartão (Visa, Master, Elo, Amex, Hipercard)
• Nome no cartão (igual impresso)
• Validade (MM/AA)
• CVV (3 ou 4 dígitos)
• CPF do titular (verificação anti-fraude)
• CEP + número (endereço cobrança Asaas)
• Telefone (opcional)

Tokia NÃO armazena número/CVV. Tudo passa direto pro Asaas que retorna token opaco. O banco Tokia guarda apenas: brand, last4, exp_month/year.

Passo 3 — Ativar Auto Top-Up

Após cadastrar cartão, na seção "Auto Top-Up":

| Campo | Significado | Default | |---|---|---| | Habilitado | Toggle on/off | off | | Threshold (R$) | Saldo abaixo disso = dispara cobrança | R$ 20 | | Recarga (R$) | Valor cobrado a cada disparo | R$ 50 | | Cartão | Qual cartão usar | primeiro cadastrado |

Clica "Salvar".

Como funciona internamente

Cron auto_topup_check roda a cada 15 minutos:

1. Lê saldo de todos users com auto-topup enabled: true
2. Pra cada user com saldo < threshold:
   • Chama Asaas POST /payments com cartão tokenizado
   • Aguarda confirmação síncrona (~5s)
   • Se OK → soma saldo + envia webhook balance.topped_up
   • Se falha → escalating (1min → 4h → 24h backoff) + webhook payment.failed

Escalating em falhas

Tokia tem proteção contra cobranças repetidas em cartão recusado:

• 1ª falha: tenta de novo em 1 minuto
• 2ª falha: tenta em 4 horas
• 3ª falha: tenta em 24 horas
• 4ª falha: desativa auto-topup + envia webhook payment.failed com motivo. Você precisa entrar em /dashboard/billing pra reativar (manual).

Motivos comuns:

• Cartão sem saldo / bloqueado
• Cartão expirado (sistema tenta retoken antes)
• Antifraude Asaas barrou

Trocar cartão sem perder saldo

1. /dashboard/billing → "Adicionar cartão" novo
2. Marca novo como "Padrão"
3. "Remover" o cartão antigo
4. Auto-topup continua funcionando com cartão novo

Cancelar Auto Top-Up

Toggle "Habilitado" → off → Salvar. Saldo atual permanece, próximas cobranças não disparam. Você volta a recarregar manual via PIX.

Webhook events relacionados

Se você tem webhook outbound configurado:

• balance.topped_up — cobrança confirmada, saldo somou
• payment.failed — cobrança recusada, contém motivo + número da tentativa

Veja manual 06-webhooks-outbound pra setup.

Próximo passo

Configure refunds self-serve pra estornar top-ups sem precisar abrir ticket.