Biz Setup Sepay Payment — Infra de pagamento VietQR ponta a ponta para Next.js
Esta skill constrói toda a infraestrutura de pagamento para landing page Next.js usando Sepay (gateway de pagamento VietQR do Vietnã). Após a conclusão: cliente preenche formulário → cria pedido → escaneia QR → transfere → webhook Sepay chega → verifica + consulta lead + dispara e-mail/Telegram. Tudo automatizado, sem necessidade de confirmação manual do admin.
Filosofia: Sepay é o caminho de menor resistência para VN — VietQR + API bancária nativa, sem necessidade de cadastro do cliente, escaneie o QR com o app bancário já instalado. Taxa de 1,5-2% mais barata que Stripe (4-5%), liquidação T+1, tier gratuito razoável para landing pages com <100 pedidos/mês.
Por que um armazenamento de leads: O webhook do Sepay só envia
content(texto que o cliente colou na transferência) + valor. O Sepay NÃO sabe quem é o cliente. É necessário um armazenamento local de leads para mapearcontent→ lead{nome, telefone, email, produto, valor}.
2 opções de armazenamento de leads — o usuário escolhe na Fase 0:
- Vercel KV (Upstash Redis) — configuração em 2 minutos, TTL nativo, gratuito com 30K comandos/mês → < 500 pedidos/mês
- Supabase Free (Postgres) — configuração em 5 minutos, consultas SQL + Studio UI, tier gratuito ~50× maior → < 2000 pedidos/mês. RECOMENDADO.
Rotas de API (/api/checkout, /api/sepay-webhook, /api/admin/leads) são independentes de provedor através de lib/leads-store.ts com re-export simples. Mudar de provedor depois = alterar 1 linha.
A skill NÃO registra a conta Sepay para o usuário (requer KYC empresarial + banco). A skill guia o usuário passo a passo e depois integra todo o código.
Quando usar esta skill
- O usuário está lançando um produto digital / curso / coaching e precisa receber pagamentos online.
- O usuário já tem uma landing page Next.js (através de
ui-ux-pro-maxou similar) e quer adicionar fluxo de pagamento. - O usuário está prestes a integrar
biz-email-setupoubiz-telegram-payment-notifymas ainda não tem infra de pagamento → esta skill é o PRÉ-REQUISITO.
NÃO use esta skill quando:
- O usuário usa Stripe/PayPal (pagamento internacional com cartão) → caso de uso diferente.
- O usuário aceita transferência bancária manual + verificação manual (baixa escala, não recomendado).
- O usuário já tem infra de pagamento e só precisa de notificação → vá direto para
/biz-email-setupou/biz-telegram-payment-notify.
Fluxo de trabalho geral (7 fases)
Fase 0: DETECTAR stack Next.js + PERGUNTAR provedor (KV / Supabase) — PORTÃO
↓
Fase 1: GUIAR usuário na configuração da conta Sepay — PORTÃO manual aguardando usuário
↓
Fase 2A (se KV): CONFIGURAR Vercel KV (instalar pacote + variáveis de ambiente + namespace KV)
Fase 2B (se Supabase): CONFIGURAR Supabase (criar projeto + migration SQL + service_role)
↓
Fase 3: CRIAR lib/leads-store.ts (wrapper de re-export) + lib/leads-{kv|supabase}.ts (implementação)
↓
Fase 4: CRIAR rota /api/checkout (formulário → pedido → armazenar)
↓
Fase 5: CRIAR rota /api/sepay-webhook (verificar + consultar + placeholders de efeitos colaterais)
↓
Fase 6: EMBUTIR VietQR na landing page (escolher 1 dos 3 padrões de UX)
↓
Fase 7: Plano de teste em 5 níveis (armazenamento → checkout → webhook → produção → (apenas Supabase) cron ping)
Fases 0 e 1 têm portão aguardando usuário. Fases 2/3/4/5/6 a skill executa ativamente.
Fase 0 — Detectar stack Next.js + escolher provedor
0.1 Detectar stack
test -f next.config.js -o -f next.config.mjs -o -f next.config.ts && echo "Next.js: ✓"
test -d app && echo "Router: App"
test -d pages && echo "Router: Pages"
test -f tsconfig.json && echo "TS: ✓"
test -f pnpm-lock.yaml && echo "pkg: pnpm" || test -f yarn.lock && echo "pkg: yarn" || echo "pkg: npm"
Se não for Next.js: PARE. Avise: "Esta skill atualmente só suporta Next.js. Seu stack atual é [X]. Devo portar a lógica para Vite/estático com Vercel function?" — aguarde usuário.
Se ambos app/ e pages/: pergunte ao usuário qual está usando.
0.2 Verificar infra existente
ls app/api/ pages/api/ lib/ 2>/dev/null
grep -E '"@vercel/kv"|"@supabase/supabase-js"|"@upstash/redis"' package.json
grep -E "SEPAY|KV_REST|SUPABASE_" .env.local 2>/dev/null
0.3 PERGUNTAR ao usuário escolher provedor
Eu detectei que você está usando Next.js [App/Pages] Router + TypeScript + [pnpm/yarn/npm].
Onde você quer armazenar os leads?
1. Vercel KV (Upstash Redis)
✓ Configuração rápida em 2 minutos (1 clique no dashboard Vercel)
✓ TTL nativo — sem preocupação com pausa do projeto
✗ Gratuito apenas 30K comandos/mês → ~500 pedidos/mês
✗ Sem SQL — filtros de admin complexos e difíceis
2. Supabase Free (Postgres) — RECOMENDADO
✓ Tier gratuito mais generoso (500MB DB + 5GB banda, consultas ilimitadas)
✓ Postgres = consultas SQL poderosas, Supabase Studio UI bonito para visualizar dados
✓ TypeScript com tipos gerados automaticamente
✓ Configuração em 5 minutos (Console + colar 2 variáveis de ambiente)
⚠ Projeto pausa automaticamente após 7 dias de inatividade → vou configurar Vercel Cron ping `/api/health` a cada 6 dias para corrigir
⚠ TTL manual via pg_cron (já configurado na migration SQL)
→ Adequado para < 2000 pedidos/mês, fácil de escalar funcionalidades de admin
Você escolhe 1 ou 2?
PORTÃO: NÃO vá para a Fase 1 até o usuário escolher. Sugira Supabase como padrão, mas force uma escolha explícita.
Após o usuário escolher, resuma o plano:
Você escolheu [Vercel KV / Supabase]. Eu vou:
- Orientá-lo na configuração da conta Sepay (5-10 minutos)
- Configurar o armazenamento de leads conforme o provedor escolhido
- Integrar o código: lib/leads-store.ts + /api/checkout + /api/sepay-webhook + incorporar VietQR
- Testar
Pronto para ir para a Fase 1?
Fase 1 — Orientar usuário na configuração da conta Sepay
Consulte references/sepay-account-setup.md para o guia completo. Resumo em 5 passos para o usuário:
Passo 1 — Registrar em my.sepay.vn
- Acesse https://my.sepay.vn → Cadastre-se
- Preencha telefone, e-mail, senha → verifique OTP
- Complete o perfil: Nome completo + CPF (pessoa física) ou CNPJ (empresa)
Passo 2 — Vincular conta bancária
Dashboard → Contas bancárias → Adicionar conta:
- Escolha o banco (Vietcombank, Techcombank, MB, ACB, VPBank, BIDV, VietinBank, TPBank, ...)
- Digite o número da conta + nome do titular (deve corresponder ao app do banco)
- Verificação automática (via API do banco) ou manual (transfira 1.000-10.000đ com código de verificação fornecido pelo Sepay)
Passo 3 — Obter chave de API
Dashboard → Configurações → API & Webhook → Criar nova chave de API:
- Nome:
landing-page-prod - Permissões:
webhook:read - Copie a chave (mostrada apenas uma vez)
Passo 4 — Configurar URL do webhook
Na mesma página → Webhook → Adicionar webhook:
- URL:
https://seu-dominio.vn/api/sepay-webhook(ficará ativo após o deploy) - Auth: API Key → cole a chave recém-criada
- Eventos:
transaction:incoming - Salvar
⚠️ Desenvolvimento local: use ngrok para expor
localhost:3000para testes com Sepay.
Passo 5 — Colar para a skill
SEPAY_WEBHOOK_API_KEY=sk_xxxxxxxxxxxxxxxxxxxx
SEPAY_BANK_ACCOUNT_NUMBER=1023456789
SEPAY_BANK_NAME=Vietcombank
SEPAY_ACCOUNT_NAME=NGUYEN VAN A
PORTÃO: NÃO vá para a Fase 2 até o usuário colar todos os dados.
Fase 2A — Configurar Vercel KV (apenas se o usuário escolheu KV na Fase 0)
Vercel KV = Upstash Redis gerenciado. Gratuito com 30K comandos/mês.
2A.1 Criar namespace KV
Dashboard Vercel → Projeto → Storage → Create Database → KV (Redis) → nome sepay-leads → Criar.
Gera automaticamente 4 variáveis de ambiente:
KV_URL=...
KV_REST_API_URL=...
KV_REST_API_TOKEN=...
KV_REST_API_READ_ONLY_TOKEN=...
Clique em Connect to Project → Vercel injeta as variáveis (Production + Preview + Development).
2A.2 Puxar variáveis para o ambiente local
npm i -g vercel # se ainda não tiver
vercel link
vercel env pull .env.local
2A.3 Instalar pacote
pnpm add @vercel/kv # ou yarn / npm install
2A.4 Verificar
node -e "
const { kv } = require('@vercel/kv');
kv.set('test', 'hello').then(() => kv.get('test')).then(v => {
console.log('KV OK:', v);
return kv.del('test');
});
"
Espere KV OK: hello. Vá para a Fase 3.
Fase 2B — Configurar Supabase Free (apenas se o usuário escolheu Supabase na Fase 0)
Consulte references/supabase-setup.md para o guia completo detalhado em 6 passos. Resumo:
2B.1 Criar conta e projeto Supabase
- https://supabase.com → Start your project → Login com GitHub
- New project:
- Nome:
sepay-leads-<marca> - Senha do banco: clique em Generate → salve
- Região: ⚠️ Southeast Asia (Singapore) (padrão us-east com latência 250ms+)
- Preço: Free
- Nome:
- Aguarde ~2 minutos de provisionamento
2B.2 Executar migration SQL
Barra lateral → SQL Editor → New query → cole o conteúdo de templates/supabase-migration.sql → Run.
Cria 4 tabelas + índices + função next_order_id() + habilita RLS + job diário de limpeza pg_cron.
Verifique a saída: 4 tabelas (leads/phone_index/order_counter/webhook_dedup) + 1 job pg_cron + next_order_id() retornando "DH000001".
Reinicie o contador (já que a verificação o incrementou):
UPDATE order_counter SET current_value = 0 WHERE id = 1;
DELETE FROM leads WHERE order_id = 'DH000001';
2B.3 Obter credenciais da API
Project Settings → API:
- Copie Project URL (
https://xxxxx.supabase.co) - Copie o segredo
service_role(NÃO a chaveanon— service_role bypassa RLS, usada no servidor)
2B.4 Colar variáveis de ambiente
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJI...
A skill verifica automaticamente:
- URL corresponde a
^https://[a-z0-9]+\.supabase\.co$ - Chave decodifica JWT, verifica
role: "service_role"(NÃOanon)
Se incorreto → avise o erro, peça para colar novamente.
2B.5 Instalar pacote
pnpm add @supabase/supabase-js
2B.6 Configurar Vercel Cron ping (evitar pausa)
O Supabase Free pausa automaticamente após 7 dias de inatividade. Solução alternativa: ping /api/health a cada 6 dias.
A skill cria app/api/health/route.ts (a partir de templates/api-health-route.ts) + adiciona ao vercel.json com:
{
"crons": [
{ "path": "/api/health", "schedule": "0 3 */6 * *" }
]
}
⚠️ Vercel Cron Hobby tem limite de 2 cron/mês. O padrão */6 days = ~5 execuções/mês → excede a cota. Opções:
- Vercel Pro ($20/mês) — cron ilimitado
- GitHub Actions workflow
.github/workflows/keep-alive.yml(GRATUITO) — a skill cria se detectar repositório GitHub remoto - cron-job.org (FREE) — configuração manual, cole a URL
/api/health
A skill escolhe a opção 2 (GitHub Actions) por padrão se o repositório tiver .git/config com remote GitHub. Caso contrário, exibe instruções da opção 3.
2B.7 Verificar
node -e "
const { createClient } = require('@supabase/supabase-js');
const sb = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_ROLE_KEY);
sb.from('order_counter').select('current_value').eq('id', 1).single().then(r => {
if (r.error) { console.error('FALHA:', r.error.message); process.exit(1); }
console.log('Supabase OK. current_value =', r.data.current_value);
});
"
Espere Supabase OK. current_value = 0. Vá para a Fase 3.
Fase 3 — Criar lib/leads-store.ts + implementação
Abstração do provedor: as rotas de API importam de lib/leads-store.ts, sem saber se o subjacente é KV ou Postgres.
Se escolheu KV (Fase 0)
Crie 2 arquivos:
lib/leads-store.ts← copietemplates/lib-leads-store-kv.ts(1 linhaexport * from './leads-kv')lib/leads-kv.ts← copietemplates/lib-leads-kv.ts(implementação KV, ~160 linhas)
Se escolheu Supabase
Crie 3 arquivos:
lib/leads-store.ts← copietemplates/lib-leads-store-supabase.ts(re-export Supabase)lib/leads-supabase.ts← copietemplates/lib-leads-supabase.ts(implementação Postgres + listLeads para admin)lib/supabase-admin.ts← copietemplates/lib-supabase-admin.ts(cliente admin em cache singleton com service_role)
Interface COMUM da API (ambas as implementações):
createLead(input) → { orderId, lead }— ID atômico + inserção + índice secundáriogetLeadByOrderId(orderId) → Lead | nullgetLeadByPhone(phone) → Lead | null— consulta de fallbackfindPendingLeadByAmountAndTime(amount, start, end) → Lead[]— Estratégia 3 de correspondência de webhookmarkLeadPaid(orderId, payment) → Lead | nullisTransactionProcessed(sepayId) → boolean— deduplicaçãomarkTransactionProcessed(sepayId) → void
TTL: 7 dias pendente / 90 dias pago. KV via parâmetro ex:. Supabase via campo expire_at + job diário pg_cron.
Mudar de provedor depois = alterar 1 linha em leads-store.ts (NÃO mexa no código da API).
Consulte references/leads-kv-schema.md (KV) ou references/supabase-leads-schema.md (Supabase) para a lógica detalhada.
Fase 4 — Criar rota /api/checkout
Consulte templates/api-checkout-app-router.ts (App Router) ou templates/api-checkout-pages-router.ts (Pages Router). Copie para o caminho correspondente.
Ambos os templates import { createLead } from '@/lib/leads-store' — independente de provedor.
Fluxo:
Cliente POST /api/checkout { name, phone, email, productName, amount }
↓
Servidor:
1. Validar (formato de telefone VN, regex de email, amount > 0)
2. createLead() → { orderId: "DH000123" }
3. Gerar URL do QR Sepay: https://qr.sepay.vn/img?acc=X&bank=Y&amount=Z&des=DH000123&template=compact
4. Retornar { orderId, amount, bankInfo, content, qrUrl }
↓
Cliente: exibir modal QR OU redirecionar para /checkout/DH000123
Fase 5 — Criar rota /api/sepay-webhook
Consulte templates/api-sepay-webhook-app-router.ts. Copie para app/api/sepay-webhook/route.ts.
O template import ... from '@/lib/leads-store' — independente de provedor.
Fluxo:
Sepay POST /api/sepay-webhook
Authorization: Apikey {SEPAY_WEBHOOK_API_KEY}
Body: SepayWebhookPayload
↓
Servidor:
1. Verificar autenticação via timingSafeEqual — proteção contra ataque de timing
2. Deduplicação antecipada: isTransactionProcessed(payload.id) → retornar 200 cedo
3. Registrar dedup PRIMEIRO — idempotente mesmo se o processamento falhar
4. Filtrar transferType === 'in' (ignorar saídas)
5. Correspondência multi-estratégia:
a. content → order_id (regex /DH\d+/)
b. content → phone (regex /0\d{9}/) → getLeadByPhone
c. amount + timestamp ±30min → findPendingLeadByAmountAndTime (aceitar apenas length === 1)
6. Rejeitar pagamento a menor, ACEITAR pagamento a maior
7. markLeadPaid(orderId, payment) → atualizar armazenamento
8. Disparar efeitos colaterais em loop try/catch (NÃO Promise.all)
9. SEMPRE retornar 200 (mesmo em erro interno) — Sepay retry Fibonacci 7 vezes se non-200
Placeholders de efeitos colaterais para biz-email-setup + biz-telegram-payment-notify serem integrados depois.
Consulte references/sepay-webhook-flow.md para a lógica de deduplicação e comportamento de retry.
Fase 6 — Incorporar VietQR na landing page
3 padrões de UX, pergunte ao usuário qual escolher:
| Padrão | Quando usar | UX |
|---|---|---|
| A. Popup modal | Produto único / compra por impulso | Enviar formulário → modal popup com QR na própria página |
| B. Página /checkout/[orderId] | Vários produtos / necessidade de compartilhar URL | Redirecionar para página dedicada com QR + instruções |
| C. Embed inline | Preferência por design minimalista | QR exibido diretamente no formulário ou abaixo dele |
A skill pergunta:
Qual padrão de UX você prefere para exibir o VietQR?
A. Modal popup B. Página /checkout/[orderId] C. Embed inline
Recomendo B se você planeja ter múltiplos produtos ou compartilhar links de pagamento via chat. A para landing page de produto único. C para formulário de leads com aparência mais integrada.
Após a escolha, a skill cria o componente/rota correspondente.
Fase 7 — Plano de teste em 5 níveis
Nível 1 — Teste de armazenamento
node -e "const { createLead, getLeadByOrderId, markLeadPaid } = require('./lib/leads-store'); async function t() {
const { orderId, lead } = await createLead({ name: 'Test', phone: '0912345678', email: '[email protected]', productName: 'Test', amount: 100000 });
console.log('Criado:', orderId);
const fetched = await getLeadByOrderId(orderId);
console.log('Consultado:', fetched?.name);
const paid = await markLeadPaid(orderId, { method: 'test', amount: 100000, sepayId: 'TEST001' });
console.log('Pago:', paid?.paid);
}
t().catch(console.error);"
Nível 2 — Teste de checkout
curl -X POST http://localhost:3000/api/checkout \
-H "Content-Type: application/json" \
-d '{"name":"Test","phone":"0912345678","email":"[email protected]","productName":"Test","amount":100000}'
Espere resposta JSON com orderId, qrUrl, content.
Nível 3 — Teste de webhook (simulado)
curl -X POST http://localhost:3000/api/sepay-webhook \
-H "Content-Type: application/json" \
-H "Authorization: Apikey $SEPAY_WEBHOOK_API_KEY" \
-d '{"id":"TEST001","transferType":"in","amount":100000,"content":"DH000001","transactionDate":"2024-01-01 12:00:00"}'
Espere 200 + verifique no banco que o lead foi marcado como pago.
Nível 4 — Teste de produção
- Faça deploy para Vercel (ou sua plataforma)
- Configure o webhook no Sepay dashboard com a URL de produção
- Faça uma transferência real via QR → verifique o fluxo completo
- Verifique logs no Vercel ou Supabase
Nível 5 — (Apenas Supabase) Teste de cron ping
curl https://seu-dominio.vercel.app/api/health
Espere 200 + verifique no Supabase se a função health_check() foi executada com sucesso.
Checklist de conclusão
- Sepay account configurada + webhook ativo
- Armazenamento de leads configurado (KV ou Supabase)
-
lib/leads-store.ts+ implementação criados -
/api/checkoutcriado e testado -
/api/sepay-webhookcriado e testado - VietQR incorporado na landing page
- Teste de ponta a ponta bem-sucedido
Após a conclusão, considere configurar:
biz-email-setup— notificar admin por email quando um lead pagarbiz-telegram-payment-notify— notificar via Telegrambiz-leads-admin-ui— painel admin para visualizar leads
Dicas de solução de problemas
| Problema | Causa provável | Solução |
|---|---|---|
| Webhook retorna 401 | API key incorreta ou não configurada | Verifique SEPAY_WEBHOOK_API_KEY no .env.local |
| Pedido não encontrado | Formato do conteúdo não corresponde | Verifique se o conteúdo da transferência inclui DH maiúsculo + número |
| QR não aparece | URL do QR inválida | Verifique SEPAY_BANK_ACCOUNT_NUMBER e SEPAY_BANK_NAME |
| Supabase pausou | 7 dias sem atividade | Execute o ping do cron ou reinicie manualmente no dashboard |
| KV command limit exceeded | Muitos pedidos no mês | Considere migrar para Supabase ou fazer upgrade do KV |