Pular para o conteúdo principal
Neste tutorial, você monta num projeto Next.js 14 ou mais novo (App Router):
  • um botão de compra que cria a compra no servidor e leva o cliente ao checkout da Valora;
  • uma Route Handler que recebe o webhook, verifica a assinatura e marca o pedido como pago.

Pré-requisitos

  • Next.js 14+ com App Router e TypeScript.
  • As variáveis VALORA_API_KEY, VALORA_WEBHOOK_SECRET e VALORA_PRODUCT_ID em .env.local. Veja Antes de começar.
Nenhuma dessas variáveis pode começar com NEXT_PUBLIC_. Elas só existem no servidor.

Integração

1

Crie o cliente da Valora

Um helper só de servidor para chamar a API e devolver erros legíveis.
lib/valora.ts
Se o pacote server-only não estiver instalado, rode npm install server-only.
2

Crie a compra com uma Server Action

A ação cria a compra e redireciona o cliente para o checkout_url.
app/actions/checkout.ts
app/page.tsx
APP_URL é a URL pública do seu app (por exemplo, https://sualoja.com).
3

Receba o webhook

Leia o corpo com request.text(): a assinatura é calculada sobre o corpo cru.
app/api/webhooks/valora/route.ts
4

Mostre o resultado ao cliente

A página de retorno lê o seu banco, que é atualizado pelo webhook. O retorno à success_url, sozinho, não prova o pagamento.
app/pedido/[id]/page.tsx

Teste

  1. Rode npm run dev e abra o túnel (ngrok http 3000).
  2. Clique em Comprar e pague no checkout de teste.
  3. Em Desenvolvedores → Webhooks, confira a entrega com status 200.
Um middleware de autenticação não pode bloquear /api/webhooks/valora. A Valora chama essa rota sem sessão de usuário.

Próximos passos

Webhooks

Novas tentativas, reenvio e boas práticas.

Checklist de produção

O que conferir antes de vender de verdade.