Pagos
Cómo cobra el pago, cómo conectar Stripe y qué le pasa a un pedido en cada paso.
Para el paquete Full Stack
Cómo cobra el pago
La tienda ofrece dos formas de pago: con tarjeta a través de Stripe y contra reembolso. El pago no tiene opción de PayPal. Ambas crean primero el pedido en la API, con los precios que calcula la API a partir de su propio catálogo, nunca con los precios que envía el navegador.
| Método | Qué le pasa al pedido |
|---|---|
| Tarjeta (Stripe) | Se guarda como pending y sin pagar. La API pide un pago a Stripe y la tienda confirma la tarjeta en la misma página. Cuando Stripe informa del pago mediante el webhook, el pedido pasa a paid y confirmed; una tarjeta rechazada lo marca como failed. |
| Contra reembolso | Se guarda como confirmed y sin pagar desde el principio. Cobras el dinero en la entrega y avanzas el pedido en el panel. |
El pago contra reembolso está seleccionado por defecto. Los invitados pueden pagar con su correo; los clientes con sesión iniciada ven el pedido en su cuenta.
El envío es gratis a partir de $75 y cuesta $9.99 por debajo, y no hay impuestos. El carrito, el resumen del pago y la API aplican la misma regla, así que el total que ve el comprador es el total que se cobra. La tienda guarda la regla en storefront/src/config/shipping.ts y la API en back-end/src/modules/orders/orders.service.ts: cambia ambas a la vez. Stripe cobra en dólares estadounidenses.
Conecta Stripe
Añade tus claves de API
Desde la página de claves de API del panel de Stripe, pon la clave secreta en
back-end/.env. Usa las claves de prueba (sk_test_…) hasta que estés listo para cobrar dinero real.back-end/.envSTRIPE_SECRET_KEY=sk_test_…Suscribe el webhook
En Stripe, añade un endpoint de webhook en la dirección de tu API seguida de
/api/payments/webhook, suscrito apayment_intent.succeededypayment_intent.payment_failed. Copia su secreto de firma enback-end/.env.back-end/.envSTRIPE_WEBHOOK_SECRET=whsec_…Da a la tienda su clave publicable
Configura la clave publicable en el
.envde la tienda y luego reconstrúyela: la clave se compila dentro. Con Docker Compose, ponla en el.envjunto adocker-compose.ymly ejecutadocker compose up --build.storefront/.envNEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_…Reinicia la API
Resultado esperado: El registro de la API dice "Stripe initialized", y el pago muestra el formulario de tarjeta.
El webhook marca el pedido como pagado
Un pedido se marca como pagado cuando Stripe llama al webhook, no cuando el comprador vuelve del pago. Sin la suscripción y su secreto de firma, los pedidos con tarjeta se quedan pendientes y sin pagar.
Para probar el webhook en tu propio equipo, la CLI de Stripe puede reenviar eventos a http://localhost:8000/api/payments/webhook y muestra el secreto de firma que debes usar mientras se ejecuta.
Sin Stripe
- Sin
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, o con cualquier cosa que no sea una clave realpk_test_…opk_live_…, la opción de tarjeta del pago dice "Card payments are unavailable right now. Please choose cash on delivery." y oculta el campo de la tarjeta. - Sin
STRIPE_SECRET_KEY, o con el valor de ejemplo de.env.example, la API no cobra ningún pago con tarjeta: un pedido realizado con el método de tarjeta se guarda como pendiente y sin pagar. - El pago contra reembolso funciona en ambos casos.
- En la tienda, con su tienda de ejemplo y sin ninguna API, el pago se completa sin llamar a Stripe y no se cobra nada.
Cobrar pagos reales
- Cambia a las claves de producción (
sk_live_…ypk_live_…) y a un webhook creado en modo producción, que tiene su propio secreto de firma. - Configura
NEXT_PUBLIC_DEMO_CHECKOUT=false, para que el pago no se rellene con un comprador generado. - Los precios se cobran en dólares estadounidenses. Para vender en otra moneda, cambia la moneda que la API envía a Stripe en
back-end/src/modules/payments/payments.service.ts, y ajustaNEXT_PUBLIC_ANALYTICS_CURRENCYpara que coincida.