Cumplir con los 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, necesitas una notificación que te indique que puedes completar el pedido después de que paguen.
Con esta guía, aprenderás a:
- Recibir una notificación cuando el cliente paga.
- Gestionar el evento.
- Utilizar la CLI de Stripe para probar rápidamente tu nuevo controlador de eventos.
- Gestionar, de forma opcional, 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.
Para comenzar, sigue la guía de instalación de la CLI de Stripe.
Podrás pasar a la siguiente etapa cuando hayas instalado la CLI de Stripe y hayas completado el proceso de inicio de sesión.
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 lugar, crea una nueva ruta para el controlador de eventos e imprime el evento recibido. Podrás verificar si la entrega está funcionando en el siguiente paso:
Pruebas
Ejecuta tu servidor (por ejemplo, en localhost:4242
). A continuación, 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
- Introduce
4242 4242 4242 4242
como número de tarjeta - Introduce cualquier fecha futura como fecha de caducidad
- Introduce cualquier número de 3 dígitos como CVC
- Introduce cualquier código postal de facturación (
90210
)
- Introduce
- Haz click en el botón Pagar
Esto es lo que deberías ver:
- Un evento
checkout.session.completed
en los resultados destripe listen
- Un extracto impreso 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, siempre debes verificar que provenga de Stripe. La biblioteca oficial de Stripe tiene soporte integrado para verificar eventos de webhook, con el que podrás actualizar el controlador de eventos:
Pruebas
Revisa 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 una solicitud sin firma al punto de conexión:
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. En función de los métodos de pago que aceptes (por ejemplo, tarjetas o monederos móviles), es posible que tengas que gestionar otros eventos. Este evento incluye el objeto Checkout Session, que contiene datos sobre tu cliente y su pago. Al gestionar este evento, también deberías tener en cuenta lo siguiente:
- Guardar una copia del pedido en tu propia base de datos.
- Enviar al cliente un recibo por correo electrónico.
- Conciliar las partidas y la cantidad adquiridas por el cliente si se utiliza
line_item.adjustable_quantity
. Si la sesión de Checkout tiene muchas líneas de artículos, puedes paginarlos con line_items.
Manejar el comportamiento de los redireccionamientos
Puedes configurar Checkout para redirigir a tus clientes después de recibir eventos de webhook. Checkout gestiona estos redireccionamientos activados por webhook de forma ligeramente diferente en función de si usas el formulario integrado o una página alojada en Stripe.
Página alojada en Stripe | El punto de conexión de tu webhook redirigirá al cliente a la success_url después de que confirmes la recepción del evento. Si tu punto de conexión está fuera de servicio o el evento no se reconoce debidamente, el controlador redirigirá al cliente a la success_url 10 segundos después de la confirmación del pago. |
Formulario integrado | El punto de conexión de tu webhook redirige a tu cliente a la return_url de inmediato. No necesitas confirmar que has recibido el evento. |
Pruebas
Asegúrate de que se esté ejecutando stripe listen
. 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: adeudo directo Bacs, Boleto, transferencias bancarias, adeudos preautorizados de Canadá, Konbini, OXXO, adeudo directo SEPA, SOFORT o adeudo directo ACH.
Cuando se reciben pagos con un método de pago de notificación con retraso, los fondos no están disponibles de inmediato. El procesamiento de los fondos puede tardar varios días, por lo que deberías retrasar el cumplimientot del pedido hasta que los fondos estén disponibles en tu cuenta. Una vez que el pago se haya realizado correctamente, el estado PaymentIntent subyacente cambia de processing
a succeeded
.
Deberás gestionar los siguientes eventos de Checkout:
Nombre del evento | Descripción | Próximos pasos |
---|---|---|
checkout.session.completed | El cliente ha autorizado correctamente el pago de débito al enviar el formulario del proceso de finalización de compra. | Espera hasta asegurarte de si el pago se ha realizado correctamente o no. |
checkout.session.async_payment_succeeded | El pago del cliente se ha realizado correctamente. | Completa el pedido de los productos o servicios comprados. |
checkout.session.async_payment_failed | El pago se ha rechazado o no se ha realizado por algún motivo. | Ponte en contacto con el cliente por correo electrónico y solicítale que efectúe un nuevo pedido. |
Todos estos eventos incluyen el objeto Sesión de Checkout
Actualiza tu controlador de eventos para completar el pedido:
Pruebas
Asegúrate de que se esté ejecutando stripe listen
. Accede a Checkout como usuario de prueba, tal y como hiciste en los pasos anteriores. Debería llegar un evento checkout.session.completed
a tu controlador de eventos, y la operación debería gestionarse correctamente.
Ahora que has completado estos pasos, puedes pasar al modo activo en la producción en el momento que 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 para registrar un webhook.