Completar pedidos con Checkout
Después de integrar Stripe Checkout o crear un enlace de pago de Stripe para llevar a tus clientes a un formulario de pago, necesitarás una notificación que indique que puedes gestionar el pedido una vez que se haya pagado.
Con esta guía, aprenderás a:
- Recibir la notificación de un evento cuando el cliente paga.
- Administrar el evento.
- Usar la CLI de Stripe para probar rápidamente tu nuevo controlador de eventos.
- Administrar, en su defecto, otros métodos de pago.
- Activar el controlador de eventos en producción.
Instalar la CLI de Stripe
La forma más rápida de desarrollar y probar webhooks a nivel local es con la CLI de Stripe.
Como primer paso, sigue la guía de instalación de la CLI de Stripe.
Una vez que tengas la CLI de Stripe instalada y hayas completado el proceso de inicio de sesión, podrás pasar a la siguiente etapa.
Crear el controlador de eventosLado del servidor
En esta sección, crearás un pequeño controlador de eventos para que Stripe pueda enviarte eventos checkout.session.completed
cuando el cliente complete el proceso de compra.
En primer término, crea una nueva ruta para el controlador de eventos e imprime el evento que recibes. Verificarás si la entrega está funcionando en el siguiente paso:
Pruebas
Ejecuta tu servidor (por ejemplo, en localhost:4242
). Luego, configura la CLI de Stripe para que reenvíe eventos a tu servidor y tú puedas probar el controlador de eventos a nivel local:
stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)
A continuación, accede a Checkout como cliente:
- Haz click en el botón de pago (probablemente lo hayas configurado en la guía Aceptar un pago)
- Completa el formulario de pago con datos de prueba
- Ingresa
4242 4242 4242 4242
como número de tarjeta - Ingresa cualquier fecha futura como fecha de vencimiento de la tarjeta
- Ingresa cualquier número de 3 dígitos para el CVC
- Ingresa cualquier código postal de facturación (
90210
)
- Ingresa
- Haz click en el botón Pagar
Esto es lo que deberías ver:
- Un evento
checkout.session.completed
en los resultados destripe listen
- Una impresión del extracto de los registros de eventos de tu servidor con el evento
checkout.session.completed
Ahora que has verificado el envío del evento, puedes añadir seguridad para garantizar que los eventos solo provengan de Stripe.
Verificar que los eventos provengan de Stripe
Cualquiera puede utilizar POST para enviar datos a tu controlador de eventos. Antes de procesar un evento, debes verificar siempre que provenga de Stripe. La librería oficial de Stripe tiene soporte integrado para verificar eventos de webhook, con el que podrás actualizar el controlador de eventos:
Pruebas
Recorre el flujo de prueba del paso anterior. Deberías seguir viendo que el evento checkout.session.completed
se imprime correctamente.
A continuación, intenta enviar al punto de conexión una solicitud sin firma:
curl -X POST \ -H "Content-Type: application/json" \ --data '{ "fake": "unsigned request" }' \ -is http://localhost:4242/webhook HTTP/1.1 400 Bad Request ... more headers
Deberías recibir un mensaje de error 400 Bad Request
porque intentaste enviar una solicitud sin firma al punto de conexión.
Ahora que ya se han configurado los elementos básicos del controlador de eventos, puedes pasar a completar el pedido.
Completar el pedidoLado del servidor
Gestiona el evento checkout.session.completed
para completar el pedido. Según los métodos de pago que aceptes (por ejemplo, tarjetas o billeteras móviles), es posible que tengas que gestionar algunos eventos adicionales. Este evento incluye el objeto Checkout Session, que contiene datos sobre tu cliente y su pago. Al gestionar este evento, también puedes considerar la posibilidad de hacer lo siguiente:
- Guardar una copia del pedido en tu propia base de datos.
- Enviar al cliente un recibo por correo electrónico.
- Conciliar los ítems de factura y la cantidad comprada por el cliente si se usa
line_item.adjustable_quantity
. Si la sesión de Checkout tiene muchos ítems de factura, puedes paginarlos a través de line_items.
Gestiona el comportamiento de redireccionamiento
Puedes configurar Checkout para redirigir a tus clientes después de recibir eventos de webhook. Checkout gestiona estas redirecciones activadas por webhooks de manera algo diferente. Esto depende de si usas el formulario insertado o una página alojada en Stripe.
Página alojada en Stripe | Tu punto de conexión de webhooks redirige al cliente a la success_url después de que confirmas que recibiste el evento. En caso de que tu punto de conexión esté fuera de servicio o no se confirme la recepción del evento debidamente, el controlador de eventos redirigirá al cliente a la success_url 10 segundos después de que el pago se efectúe correctamente. |
Formulario insertado | Tu punto de conexión de webhook redirige a tu cliente a la return_url de inmediato. No es necesario que confirmes la recepción del evento. |
Pruebas
Asegúrate de que stripe listen
se esté ejecutando. Accede a Checkout como usuario de prueba, exactamente como hiciste en los pasos anteriores. Debería llegar un evento checkout.session.completed
al controlador de eventos, y la operación debería gestionarse con éxito.
Gestionar métodos de pago con notificación diferidaLado del servidor
Precaución
Este paso es obligatorio solo si tienes pensado usar alguno de los siguientes métodos de pago: débito directo Bacs, transferencias bancarias, Boleto, débitos preautorizados de Canadá, Konbini, OXXO, débito directo SEPA, SOFORT o débito directo ACH.
Cuando recibes pagos con métodos con notificación diferida, no se dispone de los fondos de inmediato. El procesamiento puede tardar varios días, de manera que debes retrasar el cumplimiento del pedido hasta que los fondos estén en tu cuenta. Después de que el pago se efectúa correctamente, el estado del PaymentIntent subyacente cambia de processing
a succeeded
.
Tendrás que gestionar los siguientes eventos de Checkout:
Nombre del evento | Descripción | Próximos pasos |
---|---|---|
checkout.session.completed | El cliente ha autorizado correctamente el pago con débito enviando el formulario de Checkout. | Espera hasta saber si el pago se efectuó correctamente o no. |
checkout.session.async_payment_succeeded | El pago del cliente se efectuó correctamente. | Entrega los productos o servicios comprados. |
checkout.session.async_payment_failed | El pago se rechazó o falló por algún otro motivo. | Ponte en contacto con el cliente por correo electrónico y solicítale que haga un nuevo pedido. |
Todos estos eventos incluyen el objeto Checkout Session.
Actualiza el controlador de eventos para completar el pedido:
Pruebas
Asegúrate de que stripe listen
se esté ejecutando. Accede a Checkout como usuario de prueba, tal como hiciste en los pasos anteriores. Debería llegar un evento checkout.session.completed
al controlador de eventos, y la operación debería gestionarse satisfactoriamente.
Ahora que has completado estos pasos, estás en condiciones de pasar a modo de producción cuando lo decidas.
Pasar a modo de producción
Después de haber implementado el punto de conexión para el controlador de eventos en producción, debes registrar tu URL activa en Stripe. Sigue las instrucciones de la guía para registrar un webhook.