Velk vende a través de Stripe, el servicio de pagos, de dos maneras que pueden convivir en el mismo sitio:
- La tienda vende ítems de contenido de uno en uno: un ebook, un lugar en un taller, una consultoría. Un tipo de contenido marcado como vendible recibe un precio, el tema muestra un botón de compra y el comprador paga en la página de checkout de Stripe. Comprar no requiere cuenta.
- Las suscripciones cobran a los miembros cada mes o cada año por un plan: un área de cursos, artículos exclusivos, un portal de clientes. Necesitan el área de miembros, porque la cuenta es lo que une a la persona con el plan.
Los datos de la tarjeta nunca pasan por el sitio: el pago ocurre en la página de Stripe, y Stripe le avisa al sitio el resultado.
Pídele a la IA
Arma una tienda en el sitio de la panadería Masa Madre para vender talleres de panadería. Cada taller es un contenido con título, fecha, descripción y foto; haz vendible ese tipo, en pesos mexicanos. Pon un botón “Reservar mi lugar” con el precio en cada página de taller, un lugar por compra, y un interruptor “Agotado” que oculte el botón cuando el grupo se llene. Cuando se pague un pedido, envía al comprador un correo con la dirección y qué llevar. Usa Stripe en modo de prueba y dime exactamente qué crear en el panel de Stripe.
La IA marca el tipo como vendible, define la moneda de la tienda, escribe el botón y la reacción al pedido pagado, y enumera las claves y el webhook que creas en Stripe. Velk no cuenta lugares: el interruptor es la forma en que la panadería cierra un grupo.
Conectar Stripe
-
La clave secreta
STRIPE_SECRET_KEYva en.env, una sola clave para las dos funciones. Usa la clave de prueba (sk_test_…) mientras construyes. -
Un webhook por función
Un webhook es el aviso que Stripe envía al sitio cuando se confirma un pago. En el panel de Stripe creas un endpoint por cada función que uses, en la dirección del sitio, con los eventos de la tabla de abajo.
-
Su secreto de firma
Cada endpoint tiene el suyo:
STRIPE_STORE_WEBHOOK_SECRETpara la tienda,STRIPE_WEBHOOK_SECRETpara las suscripciones. Desde la v3.7.7 una función solo se activa cuando su secreto también está: con la clave sola, Stripe cobraría y el sitio nunca se enteraría, así que Velk mantiene la función apagada, y el checkout no se abre. -
La verificación
Desde la v3.7.7
schema:validaterevisa los planes, los tipos vendibles y la moneda, e indica el secreto que falta.
Los dos webhooks
| Endpoint | Eventos a suscribir |
|---|---|
| https://tu-sitio/store/stripe-webhook — la tienda | checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, checkout.session.expired |
| https://tu-sitio/member/stripe-webhook — las suscripciones | checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted |
.env de tu computadora nunca va al servidor. El .env del servidor necesita su propia clave y sus propios secretos: los de producción cuando empieces a cobrar de verdad.Vender ítems
- El campo de precio aparece solo. Cada ítem de un tipo vendible recibe un campo Precio en el panel; no lo pidas. Desde la v3.9.1 su ayuda indica la moneda de la tienda. Un ítem sin precio no se puede comprar.
- La moneda se define una vez en
site.json(store.currency, un código de tres letras como MXN, USD o EUR; BRL si no se indica). - Checkout. El botón de compra envía un ítem, o varios con sus cantidades, al checkout de Stripe. De vuelta en el sitio, el tema muestra un mensaje: pagado, o cancelado.
- Comprar una sola vez. Desde la v3.7.7 un tipo puede rechazar una segunda compra del mismo ítem (
repeat_purchasedesactivado): al miembro con sesión iniciada que ya lo pagó no se le cobra otra vez, y la cantidad es siempre uno. Quien compra sin cuenta no queda registrado, así que exige iniciar sesión donde importe.
Entrega y pedidos
Lo que ocurre después del pago le toca al tema. Velk llama a una función del tema —el webhook de pago, payment_webhook en site.json— cada vez que Stripe confirma un cambio: un pedido pagado, fallido o vencido, una suscripción iniciada, renovada o cancelada. Ahí la IA escribe “envía por correo el enlace del ebook” o “manda al comprador al CRM”, y los correos salen con la configuración SMTP del .env. Se dispara una vez por cambio real, así que un reintento de Stripe no envía el ebook dos veces, y se ejecuta mientras Stripe espera, así que el trabajo lento va en otro lado.
En el panel, Tienda → Pedidos lista los pedidos con comprador, ítems, total, fecha y estado (pendiente, pagado, expirado, fallido), con filtro por estado; cada pedido se abre con sus líneas y su referencia de Stripe. Los reembolsos se hacen en el panel de Stripe: Velk nunca reembolsa ni cancela por su cuenta, y sus pedidos no tienen estado de reembolsado.
Pídele a la IA
Los ebooks se compran una vez por miembro: cuando el miembro con sesión iniciada ya tenga uno, cambia su botón de compra por “Descargar”. Agrega una página “Mis compras” con los pedidos pagados del miembro. Comprar un ebook exige iniciar sesión.
Esto usa la regla de compra única en el tipo ebook. El enlace de descarga es tan reservado como su dirección.
Pídele a la IA
Agrega planes de pago al área de miembros de Loto Yoga: “Básico”, solo mensual, e “Ilimitado”, mensual o anual, cada uno con una descripción corta y tres beneficios. Las páginas de la “Biblioteca” abren para cualquier plan activo; las “Clases en vivo”, solo para Ilimitado. Agrega una página de precios con los botones de suscripción y un botón “Administrar suscripción” en la página del miembro. Los precios los pongo yo en el panel.
Los planes van en site.json con nombre, periodicidad y beneficios. Los precios no.
Planes y suscripciones
- Los precios viven en el panel. La pantalla Planes y suscripciones, en Ajustes, tiene un interruptor Activo y un precio por periodicidad para cada plan, más la moneda (BRL si queda en blanco, independiente de la moneda de la tienda). Velk crea el producto y el precio en Stripe la primera vez que se usan. Un precio nuevo vale para las suscripciones nuevas; quien ya está suscrito sigue con el anterior. Desde la v3.9.1 la pantalla sigue el idioma del panel y no tiene pestañas de idioma: un precio no se traduce.
- Un plan por miembro por defecto: una segunda suscripción responde
already_subscribed. Desde la v3.7.7members.multiple_planspermite varios, uno por plan. - El portal del cliente es la página de Stripe donde el miembro cambia la tarjeta, cambia de plan o cancela. El tema muestra un botón hacia él, y tú eliges qué permite en el panel de Stripe; con varios planes por miembro, desactiva allí el cambio de plan.
- El acceso sigue el estado de Stripe. Un miembro con la tarjeta rechazada conserva el acceso mientras Stripe reintenta; las suscripciones canceladas o impagas lo pierden. Quien programa la cancelación para el final del período conserva el acceso hasta esa fecha.
- La lista de miembros gana la columna Plan, y un “!” rojo marca a quien tenga más suscripciones activas de las que permite la regla (dos pestañas pagando a la vez, por ejemplo). Resuélvelo en Stripe.