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:

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

Mensagens de erro

| Erro | Causa | Solução | |---|---|---| | refund_window_expired | Passou de 7 dias | Email contato@usetokia.com (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 contato@usetokia.com |

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 (Sprint 14) — se você tiver configurado

Próximo passo

Setup webhooks outbound pra integrar eventos Tokia no seu sistema.

Refund self-serve de top-ups