O Velk vende pelo Stripe, o serviço de pagamentos, de dois jeitos que podem conviver no mesmo site:
- A loja vende itens de conteúdo, um a um: um ebook, uma vaga de oficina, uma consultoria. Um tipo de conteúdo marcado como vendável ganha preço, o tema mostra um botão de compra e o comprador paga na página de checkout do Stripe. Não precisa de conta para comprar.
- As assinaturas cobram membros por mês ou por ano por um plano: uma área de curso, artigos exclusivos, um portal do cliente. Elas dependem da área de membros, porque é a conta que amarra a pessoa ao plano.
Os dados do cartão nunca passam pelo site: o pagamento acontece na página do Stripe, e o Stripe avisa o site do resultado.
Peça à IA
Monta uma loja no site da Padaria Fermento para vender oficinas de panificação. Cada oficina é um conteúdo com título, data, descrição e foto; deixa esse tipo vendável, em reais. Põe um botão “Garantir minha vaga” com o preço em cada página de oficina, uma vaga por compra, e uma chave “Esgotado” que esconde o botão quando a turma lotar. Quando o pedido for pago, manda um e-mail para o comprador com o endereço e o que levar. Usa o Stripe em modo de teste e me diz exatamente o que criar no painel do Stripe.
A IA marca o tipo como vendável, define a moeda da loja, escreve o botão e a reação ao pedido pago, e lista as chaves e o webhook que você cria no Stripe. O Velk não conta vagas: a chave é o jeito de a padaria fechar uma turma.
Conectando o Stripe
-
A chave secreta
A
STRIPE_SECRET_KEYvai no.env, uma chave para os dois recursos. Use a chave de teste (sk_test_…) enquanto constrói. -
Um webhook por recurso
Webhook é o aviso que o Stripe manda para o site quando um pagamento é confirmado. No painel do Stripe você cria um endpoint para cada recurso em uso, no endereço do site, com os eventos da tabela abaixo.
-
O segredo de assinatura
Cada endpoint tem o seu:
STRIPE_STORE_WEBHOOK_SECRETpara a loja,STRIPE_WEBHOOK_SECRETpara as assinaturas. Desde a v3.7.7 um recurso só liga quando o segredo dele também está lá: só com a chave, o Stripe cobraria e o site nunca saberia, então o Velk mantém o recurso desligado, e o checkout não abre. -
A conferência
Desde a v3.7.7 o
schema:validateconfere os planos, os tipos vendáveis e a moeda, e aponta o segredo que falta.
Os dois webhooks
| Endpoint | Eventos para assinar |
|---|---|
| https://seu-site/store/stripe-webhook — a loja | checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, checkout.session.expired |
| https://seu-site/member/stripe-webhook — as assinaturas | checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted |
.env do seu computador nunca vai para o servidor. O .env do servidor precisa da própria chave e dos próprios segredos: os de produção quando você começar a cobrar de verdade.Vendendo itens
- O campo de preço vem sozinho. Todo item de um tipo vendável ganha um campo Preço no painel; não peça um. Desde a v3.9.1 a ajuda dele diz a moeda da loja. Item sem preço não pode ser comprado.
- A moeda é definida uma vez no
site.json(store.currency, um código de três letras como BRL ou USD; BRL quando ausente). - Checkout. O botão de compra manda um item, ou vários com as quantidades, para o checkout do Stripe. De volta ao site, o tema mostra uma mensagem: pago, ou desistiu.
- Comprar uma vez só. Desde a v3.7.7 um tipo pode recusar a segunda compra do mesmo item (
repeat_purchasedesligado): o membro logado que já pagou por ele não é cobrado de novo, e a quantidade é sempre um. Quem compra sem conta não é rastreado, então exija login onde isso importa.
Entrega e pedidos
O que acontece depois do pagamento é com o tema. O Velk chama uma função do tema — o webhook de pagamento, payment_webhook no site.json — cada vez que o Stripe confirma uma mudança: pedido pago, recusado ou expirado, assinatura iniciada, renovada ou cancelada. É ali que a IA escreve “manda o link do ebook por e-mail” ou “manda o comprador para o CRM”, e os e-mails saem pelas configurações de SMTP do .env. Ela dispara uma vez por mudança real, então uma nova tentativa do Stripe não manda o ebook duas vezes, e roda enquanto o Stripe espera, então trabalho demorado fica para outro lugar.
No painel, Loja → Pedidos lista os pedidos com comprador, itens, total, data e status (pendente, pago, expirado, falhou), com filtro por status; cada pedido abre com os itens e a referência do Stripe. Reembolso se faz no painel do Stripe: o Velk nunca reembolsa nem cancela sozinho, e os pedidos dele não têm status de reembolsado.
Peça à IA
Os ebooks são comprados uma vez por membro: quando o membro logado já tiver um, troca o botão de compra por “Baixar”. Cria uma página “Minhas compras” com os pedidos pagos do membro. Comprar ebook exige login.
Isso usa a regra de compra única no tipo ebook. O link de download é tão reservado quanto o endereço dele.
Peça à IA
Põe planos pagos na área de membros do Studio Lótus: “Básico”, só mensal, e “Ilimitado”, mensal ou anual, cada um com uma descrição curta e três benefícios. As páginas da “Biblioteca” abrem para qualquer plano ativo; as “Aulas ao vivo”, só para o Ilimitado. Cria uma página de preços com os botões de assinar e um botão “Gerenciar assinatura” na página do membro. Os preços eu coloco no painel.
Os planos vão para o site.json com nome, periodicidade e benefícios. O preço não.
Planos e assinaturas
- O preço mora no painel. A tela Planos & Assinaturas, em Configurações, tem uma chave Ativo e um preço por periodicidade para cada plano, mais a moeda (BRL quando em branco, separada da moeda da loja). O Velk cria o produto e o preço no Stripe no primeiro uso. Preço novo vale para assinaturas novas; quem já assina continua no antigo. Desde a v3.9.1 a tela segue o idioma do painel e não tem abas de idioma: preço não tem tradução.
- Um plano por membro por padrão: uma segunda assinatura responde
already_subscribed. Desde a v3.7.7 omembers.multiple_planspermite vários, um por plano. - O portal do cliente é a página do Stripe onde o membro troca o cartão, muda de plano ou cancela. O tema mostra um botão para ele, e você escolhe o que ele permite no painel do Stripe; com vários planos por membro, desligue a troca de plano lá.
- O acesso segue o status do Stripe. Membro com cartão recusado mantém o acesso enquanto o Stripe tenta de novo; assinatura cancelada ou não paga perde. Quem agenda o cancelamento para o fim do período mantém o acesso até essa data.
- A lista de membros ganha a coluna Plano, e um “!” vermelho marca quem tem mais assinaturas ativas do que a regra permite (duas abas pagando ao mesmo tempo, por exemplo). Resolva no Stripe.