Hospedagem com 20% de desconto comprando pelo link

Loja e assinaturas

Venda itens avulsos e cobre membros por mês ou por ano pelo Stripe: campo de preço, checkout, pedidos, entrega automática e o portal do cliente.

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

  1. A chave secreta

    A STRIPE_SECRET_KEY vai no .env, uma chave para os dois recursos. Use a chave de teste (sk_test_…) enquanto constrói.

  2. 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.

  3. O segredo de assinatura

    Cada endpoint tem o seu: STRIPE_STORE_WEBHOOK_SECRET para a loja, STRIPE_WEBHOOK_SECRET para 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.

  4. A conferência

    Desde a v3.7.7 o schema:validate confere os planos, os tipos vendáveis e a moeda, e aponta o segredo que falta.

Os dois webhooks

EndpointEventos para assinar
https://seu-site/store/stripe-webhook — a lojacheckout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, checkout.session.expired
https://seu-site/member/stripe-webhook — as assinaturascheckout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted
O que a IA roda
# confere planos, tipos vendáveis e a moeda; aponta o segredo que falta $ ./bin/velk schema:validate ✓ site.json is valid.
O .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_purchase desligado): 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 o members.multiple_plans permite 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.