Refund self-serve de top-ups

Você fez recarga errada ou desistiu de usar? Tokia permite refund parcial ou total direto no dashboard dentro de 7 dias do pagamento.

Regras

• Janela: 7 dias corridos do paid_at da transação
• Saldo suficiente: você não pode estornar mais do que ainda está disponível no saldo (gastou parte? só estorna o que sobrou)
• Asaas processa: pix volta na mesma conta origem; cartão estorna na fatura próxima
• NF: nota fiscal original é cancelada automaticamente

Passo 1 — /dashboard

Card "Recargas recentes" lista últimas 5 transações. Cada linha "Confirmado" tem botão "Estornar" (visível só dentro da janela 7d).

Passo 2 — Modal estorno

Clica "Estornar". Modal mostra:

• Valor da recarga: ex: R$ 100,00
• Saldo disponível pra estorno: ex: R$ 87,50 (você já gastou R$ 12,50)
• Tipo:
  • Total: devolve tudo que pode (R$ 87,50)
  • Parcial: você digita valor entre R$ 0,01 e disponível

Passo 3 — Confirma

Clica "Confirmar estorno". Tokia:

1. Chama Asaas POST /payments/:id/refund com valor solicitado
2. Asaas processa (instantâneo pix, ~5min cartão)
3. Saldo Tokia decrementa
4. NF Asaas é cancelada
5. Email confirmação dispara via Resend

Mensagens de erro

Erro	Causa	Solução
refund_window_expired	Passou de 7 dias	Email suporte@usetokia.com.br (caso a caso)
already_refunded	Top-up já estornado	Confere histórico Asaas
balance_insufficient_for_refund	Gastou mais do que tinha pra estornar	Estorne só o disponível
topup_not_paid	Top-up ainda pendente	Aguarda confirmação ou expira
asaas_refund_failed	Asaas rejeitou (raro)	Email suporte@usetokia.com.br

Via API (programmatic)

curl -X POST https://api.usetokia.com/topups/{topup_id}/refund \
  -H "Authorization: Bearer <JWT_LOGTO>" \
  -H "Content-Type: application/json" \
  -d '{"amount_brl": 50}'

Sem amount_brl no body = refund total (do disponível).

⚠️ Esse endpoint usa JWT Logto (sessão de user logado), não sk-tokia-... API key. É operação de account, não de IA.

Auditoria

Toda operação fica logada em:

• /dashboard/billing → seção "Histórico de transações"
• Email pro inael.rodrigues@gmail.com (admin) quando refund > R$ 500
• Webhook outbound topup.refunded — se você tiver configurado

Próximo passo

Setup webhooks outbound pra integrar eventos Tokia no seu sistema.