Commerce Stripe
Proporciona integración de Drupal Commerce con el procesamiento de pagos de Stripe, soportando tanto el moderno Payment Element como el legacy Card Element con características como 3D Secure, webhooks y Stripe Connect.
commerce_stripe
Install
composer require 'drupal/commerce_stripe:^2.1'
composer require 'drupal/commerce_stripe:8.x-1.3'
Overview
Commerce Stripe integra Drupal Commerce con la plataforma de procesamiento de pagos de Stripe, permitiendo a los comerciantes aceptar tarjetas de crédito, billeteras digitales (Apple Pay, Google Pay) y métodos de pago alternativos (Klarna, Affirm, Alipay, etc.) a través de la infraestructura segura de pagos de Stripe.
El módulo proporciona dos plugins de pasarela de pago: el recomendado Stripe Payment Element que renderiza el formulario de pago moderno y completamente alojado de Stripe soportando múltiples métodos de pago, y el legacy Stripe Card Element para integraciones exclusivas de tarjetas de crédito. Ambos soportan Strong Customer Authentication (3D Secure) para cumplimiento con PSD2.
Las características principales incluyen sincronización automática de payment intent cuando cambian los totales del pedido, soporte de webhooks para actualizaciones de estado de pago en tiempo real, y Stripe Connect OAuth para configuración simplificada de cuentas de comerciante. El módulo utiliza Stripe.js para asegurar que los datos sensibles de tarjetas nunca toquen tu servidor, reduciendo el alcance de cumplimiento PCI.
Features
- Integración de Stripe Payment Element soportando múltiples métodos de pago incluyendo tarjetas de crédito, billeteras digitales y opciones de compra ahora y paga después
- Legacy Stripe Card Element para flujos de checkout exclusivos de tarjetas de crédito
- Soporte de Strong Customer Authentication (SCA) y 3D Secure 2.0 para cumplimiento con PSD2
- Gestión completa del ciclo de vida de pagos: operaciones de autorización, captura, anulación y reembolso
- Stripe Connect OAuth para configuración simplificada de claves API sin entrada manual de claves
- Soporte de webhooks para sincronización de pagos en tiempo real entre Stripe y Drupal
- Actualizaciones automáticas de montos de payment intent cuando cambian los totales del carrito
- Detección avanzada de fraude con recolección opcional de señales de interacción del usuario
- Etiquetas de visualización de checkout personalizables con soporte de logos de métodos de pago
- Submódulo opcional para registro y solución de problemas de eventos de webhook
Use Cases
Checkout de comercio electrónico estándar
Usa Stripe Payment Element para una experiencia de checkout moderna soportando tarjetas de crédito, Apple Pay, Google Pay y otros métodos de pago. Configura el método de captura 'automatic' para cobro inmediato de pagos y uso 'on_session' para escenarios de compra única.
Comercio por suscripción
Configura el uso de método de pago 'off_session' para permitir que el sitio cobre a los clientes por suscripciones recurrentes sin su participación activa. Los métodos de pago se almacenarán y serán reutilizables para cargos futuros.
Flujo de trabajo de autorización y captura
Usa el método de captura 'manual' para colocar retenciones en las tarjetas de los clientes en el checkout, luego captura los fondos más tarde cuando se cumplan los pedidos. Soporta capturas parciales y operaciones de anulación a través de la interfaz de administración de pedidos.
Ventas internacionales multidivisa
Stripe Payment Element maneja automáticamente la conversión de divisas y muestra los métodos de pago apropiados basándose en la ubicación del cliente y la divisa configurada.
Compra ahora paga después
Habilita los métodos de pago Klarna o Affirm a través de Stripe Payment Element para ofrecer a los clientes opciones de pago en cuotas. Estos son métodos de pago de uso único configurados automáticamente.
Procesamiento de webhooks de alto volumen
Instala el submódulo commerce_stripe_webhook_event con Advanced Queue para diferir el procesamiento de webhooks. Los webhooks se registran inmediatamente y se procesan en segundo plano, mejorando los tiempos de respuesta y la confiabilidad.
Plataforma/Marketplace con Stripe Connect
Usa la autenticación OAuth de Stripe Connect para permitir que los vendedores del marketplace conecten sus cuentas de Stripe sin compartir claves API. El módulo maneja el flujo OAuth y el almacenamiento de tokens automáticamente.
Tips
- Almacena las credenciales API de producción en settings.php usando $config['commerce_payment.commerce_payment_gateway.tu_pasarela']['configuration']['secret_key'] para mantenerlas fuera de la base de datos.
- Usa la autenticación de Stripe Connect para una gestión más fácil de claves y la capacidad de revocar acceso sin cambiar las claves API.
- Instala el submódulo commerce_stripe_webhook_event para visibilidad en la entrega y procesamiento de webhooks, especialmente útil durante el desarrollo y la solución de problemas.
- Para desarrollo local, usa la CLI de Stripe para reenviar webhooks: stripe listen --forward-to tu.ddev.site/payment/notify/tu_pasarela
- Se recomienda el Payment Element sobre el Card Element para nuevas integraciones ya que soporta más métodos de pago y recibe actualizaciones continuas de Stripe.
- Establece 'capture_method' en 'automatic_async' para mejorar el rendimiento del checkout ya que reduce la latencia comparado con la captura sincrónica.
- Carga Stripe.js en cada página (en configuración global) para mejores puntuaciones de detección de fraude, especialmente para negocios de alto riesgo.
Technical Details
Admin Pages 3
/admin/commerce/config/stripe
Configura los ajustes globales de Commerce Stripe que aplican a todas las pasarelas de pago de Stripe.
/admin/commerce/config/payment-gateways/manage/{gateway_id}
Configura una pasarela de pago Stripe Payment Element con autenticación, configuración de webhooks, opciones de pago y personalización de apariencia.
/admin/commerce/config/stripe-webhook-events
Ver y gestionar eventos de webhook enviados a tu sitio por Stripe. Útil para solucionar problemas de pagos y monitorear la entrega de webhooks. (Requiere el submódulo commerce_stripe_webhook_event)
Permissions 2
Hooks 1
hook_js_settings_alter
Permite personalizar la configuración de JavaScript pasada a los elementos de Stripe antes de la inicialización.
Troubleshooting 7
Asegúrate de que el panel de checkout 'Stripe review' esté habilitado en el paso 'Revisión' en la configuración de tu flujo de checkout en /admin/commerce/config/checkout-flows.
El panel de revisión de Stripe debe estar habilitado incluso para integraciones de Card Element. Sin él, el JavaScript requerido para mostrar el modal 3D Secure no se cargará.
Verifica que la URL del endpoint del webhook coincida con /payment/notify/[gateway_id], asegúrate de que el secreto de firma esté copiado correctamente del panel de Stripe, y comprueba que el firewall de tu servidor permita solicitudes entrantes desde los rangos de IP de Stripe.
Asegúrate de que tus claves API coincidan con el modo seleccionado (prueba vs. producción). Si usas claves de marcador de posición, desmarca 'Validar claves API al enviar el formulario'. Para producción, almacena las claves en settings.php usando anulaciones de configuración.
El OrderPaymentIntentSubscriber maneja esto automáticamente. Asegúrate de que el módulo esté correctamente instalado y que el servicio suscriptor de eventos esté registrado. Revisa los logs de commerce_stripe para cualquier error.
Habilita el submódulo commerce_stripe_webhook_event para recuperarse de fallos de retorno. El webhook payment_intent.succeeded puede completar pedidos cuando la ruta de retorno falla.
Apple Pay requiere verificación de dominio en tu panel de Stripe. Sube el archivo de verificación a /.well-known/apple-developer-merchantid-domain-association en tu servidor web.
Security Notes 6
- El módulo usa Stripe.js que asegura que los datos sensibles de tarjetas nunca toquen tu servidor, reduciendo significativamente los requisitos de cumplimiento PCI DSS.
- Siempre usa HTTPS en producción; Stripe.js fallará en conexiones inseguras.
- Almacena las claves API de producción fuera de la base de datos usando anulaciones de configuración en settings.php para prevenir exposición en volcados de base de datos o exportaciones de configuración.
- Habilita la verificación de firma de webhook configurando el secreto de firma del webhook para prevenir solicitudes de webhook falsificadas.
- Los permisos 'administer commerce stripe' y de eventos de webhook deben restringirse solo a administradores de confianza.
- Revisa la documentación de seguridad de Stripe en https://stripe.com/docs/security para mejores prácticas adicionales.