Integraciones · Documentación de Winal

Plugins oficiales para plataformas de terceros, mantenidos en integrations/ del repo (hoy: WooCommerce), y el migrador para traer tu catálogo desde Stripe o Conekta si vienes de otra plataforma.

WooCommerce

Winal Payments para WooCommerce (v0.1.0) acepta tarjeta, SPEI, CoDi/DiMo y OXXO en tu tienda a través del checkout hosteado de Winal (/pay/{slug}). El pago lo procesa Winal (tokenización client-side, PCI SAQ A); WooCommerce solo crea el "link de cobro" y confirma la orden cuando llega el webhook firmado.

Requisitos

WordPress 6.3+ con WooCommerce 8.0+, PHP 8.1+, una clave sk_test_... del portal de Winal, y tu tienda cobrando en MXN — la única moneda que soporta esta versión.

Instalación en 3 pasos

Instala el plugin: comprime integrations/woocommerce/winal-payments/ en un .zip (o cópiala por FTP/SSH a wp-content/plugins/winal-payments/), súbela desde WordPress admin → Plugins → Añadir nuevo → Subir plugin, y actívala.
Registra el webhook: la pantalla de ajustes del plugin muestra la URL exacta de tu receptor (https://tu-tienda.mx/wc-api/winal_webhook). Regístrala en el portal de Winal (Webhooks → Agregar endpoint) o por API:
bash
```
curl -s https://api.winal.com.mx/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tu-tienda.mx/wc-api/winal_webhook" }'
```
Copia el secret (whsec_...) de la respuesta al campo del plugin de inmediato — solo se muestra una vez.
Llena los ajustes en WooCommerce → Ajustes → Pagos → Winal: URL base de Winal, clave secreta de prueba/producción y el webhook secret correspondiente. El plugin usa el par de credenciales del modo activo (casilla "Modo de pruebas"), igual que el patrón estándar de otros gateways de WooCommerce.

Cómo correlaciona el webhook con tu orden

El plugin usa Payment Links, no payment_intents directos: al pagar, process_payment() crea un link (POST /v1/payment_links) y redirige al comprador al checkout hosteado de Winal. La correlación de vuelta hacia la orden de WooCommerce es exacta por metadata: los intents nacidos de un Payment Link traen metadata.payment_link_id (ver Eventos y polling / Webhooks), y match_order_for_event() lo compara contra el _winal_payment_link_id que la orden guardó al crear su link — sin adivinar por monto salvo como respaldo para eventos sin metadata, y nunca marca una orden pagada si el resultado sigue siendo ambiguo.

La orden se confirma por webhook, no por redirección

El checkout hosteado de Winal (v1) no tiene return_url: la pantalla de "Gracias por tu pedido" de WooCommerce se muestra antes de que el pago se confirme (con un aviso explícito), y la orden pasa a Procesando/Completado segundos después, cuando llega payment_intent.succeeded.

Limitaciones conocidas de esta v0.1.0: solo MXN, sin reembolsos/webhooks de refund.* desde el plugin (usa el portal), y cada reintento de pago genera un Payment Link nuevo. Detalle completo, estructura de archivos y roadmap en integrations/woocommerce/winal-payments/README.md.

Migrador desde Stripe/Conekta

Si ya cobras con Stripe o Conekta, el migrador trae tu catálogo de clientes y cupones a Winal sin que tengas que recapturarlos a mano. Se corre desde portal → Migrador: pegas la llave de API de la plataforma de origen (Stripe secret key / Conekta private key) — nunca se guarda, solo vive en memoria durante esa corrida— y eliges origen (stripe o conekta). Hay un modo de simulación (dry run) que reporta qué importaría sin escribir nada todavía.

Qué SÍ trae	Qué NO trae
Clientes (con metadata de origen para trazabilidad), cupones (porcentaje/monto fijo, duración, tope de redenciones), y suscripciones — estas últimas se crean pausadas, con un Payment Link de re-inscripción de un solo uso para que el cliente vuelva a capturar su forma de pago.	Tarjetas ni ningún método de pago guardado — imposible por diseño (PCI): los tokens de tarjeta de Stripe/Conekta no son portables vía API hacia ningún otro proveedor. Tampoco migra historial de cobros/reembolsos/disputas, facturas, ni suscripciones que ya estaban canceladas en el origen.

Por eso las suscripciones migradas nacen pausadas en vez de activas: sin la tarjeta, Winal no tiene con qué cobrar el siguiente período hasta que el cliente la vuelva a capturar por el link de re-inscripción. Es seguro re-correr el migrador — es idempotente por diseño, así que una segunda corrida sobre el mismo origen no duplica lo ya importado.