Tu app vende un recurso digital. El comprador vuelve desde Stripe Checkout a una página que dice «Pago completado», y tu código le abre el archivo. Parece suficiente hasta que una persona paga y pierde la conexión antes de volver a tu web, o un método de pago tarda en confirmarse. Si el acceso depende solo de esa página, puedes dejar a un cliente sin producto o abrirlo antes de recibir el pago.
La guía de Stripe para completar pedidos exige escuchar webhooks para que el servidor conozca el resultado aunque el navegador no regrese. Esta es una guía de prueba para un pago único en modo sandbox, no una integración ya ejecutada con la cuenta de Joseph. Los pasos y números de tarjeta vienen de la documentación oficial; no se procesó un pago real aquí.
La regla: el retorno informa, el servidor decide
La success_url puede mostrar un mensaje y el ID de la sesión de Checkout, pero no debe ser la única señal que activa un curso, descarga o plan. Stripe indica que el cliente puede pagar correctamente y cerrar la pestaña, quedarse sin internet o no visitar la página de regreso. También distingue pagos inmediatos de métodos cuyo éxito llega después.
Diseña una función de entrega que reciba un Checkout Session ID, recupere la sesión desde Stripe, compruebe payment_status y guarde en tu base de datos que esa sesión ya fue atendida. Si recibe el mismo ID de nuevo, no debe enviar dos licencias, correos o descargas. Stripe advierte que esa función puede ejecutarse varias veces e incluso en paralelo. La restricción única sobre el ID de sesión debe estar en la base de datos, no solo en una variable de memoria.
Prepara una compra de prueba
- Entra al sandbox de Stripe y crea un producto con precio de prueba. Mantén separadas las claves
sk_test_ysk_live_; nunca pegues la secreta en el frontend ni en un repositorio. - Configura Checkout para un pago único. Si creas la sesión por API, utiliza
mode=payment, el ID de precio y unasuccess_urlque incluya{CHECKOUT_SESSION_ID}. El placeholder sirve para mostrar el estado al comprador y para que tu servidor recupere la sesión. - Registra un endpoint webhook que reciba
checkout.session.completedy, si habilitas métodos diferidos,checkout.session.async_payment_succeededycheckout.session.async_payment_failed. Verifica la firma de Stripe con el cuerpo sin modificar y el secretowhsec_del endpoint antes de procesar eventos. - En la función de entrega, consulta la sesión y sus artículos, confirma el estado de pago y guarda el ID como atendido antes de realizar acciones que no puedas repetir. Si tu proceso tiene varios pasos, usa una transacción o un estado de trabajo recuperable para evitar entregas parciales.
Para iniciar una sesión desde terminal, este fragmento de la documentación de Stripe es una plantilla: reemplaza la clave de prueba, el ID del precio y tu dominio. La respuesta devuelve una URL de Checkout. No ejecutes la versión con claves reales mientras solo estás verificando el flujo.
curl https://api.stripe.com/v1/checkout/sessions \
-u "SK_TEST_DE_TU_SANDBOX:" \
-d "line_items[0][price]=PRICE_ID_DE_PRUEBA" \
-d "line_items[0][quantity]=1" \
-d mode=payment \
--data-urlencode "success_url=https://tu-dominio.example/gracias?session_id={CHECKOUT_SESSION_ID}"
Cuatro pruebas antes de cobrar
Instala la Stripe CLI según su guía oficial, inicia tu endpoint local y reenvía los eventos con:
stripe listen --forward-to localhost:4242/webhook
La CLI muestra un secreto whsec_ de prueba; úsalo solo para ese listener. Luego completa Checkout con la tarjeta de prueba 4242 4242 4242 4242, una fecha futura y cualquier CVC de tres dígitos, como indica Stripe Testing. Comprueba esta matriz en tu propia app:
| Escenario | Resultado esperado |
|---|---|
| Pago de prueba y regreso normal | El webhook verifica el pago y la entrega ocurre una vez. |
| Pago de prueba y pestaña cerrada antes del retorno | El webhook entrega igualmente; la página de gracias no es requisito. |
| El mismo evento llega otra vez | El ID ya atendido impide duplicar licencias o correos. |
| Pago rechazado o diferido | No se entrega hasta confirmar éxito; se muestra un estado pendiente o fallo. |
Una tarjeta de éxito solo cubre el primer camino. Stripe documenta tarjetas para rechazos y flujos con autenticación; elige las que correspondan a los métodos que aceptarás. Si permites pagos diferidos, espera checkout.session.async_payment_succeeded antes de entregar y atiende el evento de fallo. No llames «pagado» a un checkout.session.completed cuyo payment_status todavía indica que falta confirmación.
Qué queda pendiente para producción
Este artículo no fija comisión ni disponibilidad por país: dependen de tu cuenta, mercado y método de pago. Verifica la tabla vigente de Stripe y tus obligaciones antes de habilitar cobros reales. También faltan en esta plantilla el código de tu base de datos, manejo de reembolsos, soporte al cliente y conciliación contable. La decisión que sí puedes tomar hoy es probar en sandbox que la entrega sale del estado verificado en el servidor y que un evento repetido no concede acceso dos veces.
