Introducción

El plugin Wompi Payment Method añade un medio de pago en M&S CRM para cobrar facturas a través de la pasarela colombiana Wompi. Permite dos modos de integración: Web Checkout (redirección) y Enlaces de pago.

El propósito de este documento es explicar paso a paso cómo instalar, configurar y utilizar el módulo, además de detallar el flujo de pago, las claves necesarias, las notificaciones (webhooks) y las consideraciones de seguridad.

Requisitos Previos

Importante

  • Versión de M&S: el plugin está diseñado para M&S CRM >= 3.x. Asegúrate de utilizar una versión estable.
  • Cuenta en Wompi: necesitas una cuenta de comercio en Wompi.
  • Servidor con HTTPS: Wompi recomienda emplear HTTPS tanto para el formulario de pago como para la URL de eventos (webhook).
  • Conocimientos básicos de M&S: debes tener acceso al panel de administración y derechos para instalar plugins.

Claves y Secretos

En la sección "Desarrolladores → Claves y secretos técnicos" obtendrás:

Tipo Sandbox Producción
Clave Pública pub_test_ pub_prod_
Clave Privada prv_test_ prv_prod_
Secreto Eventos test_events_ prod_events_
Secreto Integridad test_integrity_ prod_integrity_

Instalación del Plugin

Proceso de Instalación

  1. Descarga y extracción: Tras adquirir el plugin, descarga Wompi_Payment_Method.zip y extrae el contenido.
  2. Carga en directorio: Copia Wompi_Payment_Method dentro de app/Modules o custom/Modules.
  3. Base de datos: Ejecuta /wompi_payment_method/install/do_install.php o importa database.sql.
  4. Activación: En M&S, ve a Settings → Payment Methods y activa Wompi.

Configuración del Método de Pago

Claves y Secretos

  • Clave pública: Obligatoria, prefijo pub_, se usa en Web Checkout.
  • Clave privada: Solo para Enlaces de pago, prefijo prv_.
  • Secreto de integridad: Para validar firma signature:integrity.
  • Secreto de eventos: Para validar webhooks con X-Event-Checksum.

Otros Campos Importantes

  • Ambiente: sandbox para pruebas, producción para vivo.
  • Prefijo de referencia: Personaliza referencias (ej: MS-).
  • Forzar moneda: Usa COP para Colombia.
  • Monto mínimo: Establece valor mínimo para pagos.
  • Pagos parciales: Permite montos menores al saldo.

Flujo de Pago con Web Checkout

Proceso Paso a Paso

  1. Inicio: Cliente hace clic en "Pagar con Wompi" → M&S genera código de verificación.
  2. Redirección: Plugin construye URL /wompi_payment_method/checkout/<verification_code>.
  3. Firma: Se calcula SHA256 con: referencia + monto + moneda + secret.
  4. Formulario: Se envían parámetros a https://checkout.wompi.co/p/.
  5. Pago: Usuario completa datos en interfaz Wompi.
  6. Retorno: Wompi redirige con parámetro id de transacción.

Firma de Integridad

La firma se construye concatenando:

referencia + monto_en_centavos + moneda + integrity_secret
↓ SHA256 ↓
signature:integrity

Enlaces de Pago (Payment Links)

Funcionalidad

Los Enlaces de pago generan un link único mediante la API de Wompi. Útil para enviar por correo, chat o redes sociales.

Requisitos Técnicos

  1. Clave privada: Configurar prv_test_ o prv_prod_.
  2. API Request: POST a /v1/payment_links con header Authorization: Bearer <private_key>.
  3. Parámetros: JSON con name, description, single_use, etc.
  4. Respuesta: HTTP 201 con data.url del enlace público.

Gestión de Transacciones y Estados

Estado Descripción Acción en M&S
APPROVED Transacción autorizada y pago capturado ✅ Registrar pago
DECLINED Transacción rechazada por medio de pago ❌ Mostrar error
VOIDED Transacción anulada (solo tarjetas) ❌ No registrar
ERROR Error interno en medio de pago ❌ Mostrar error
PENDING Estado transitorio ⏳ Esperar evento

Consulta de Estados

Puedes conocer el estado mediante:

  • Consulta API: GET /v1/transactions/{id}
  • Eventos webhook: transaction.updated automático

Webhooks y Notificaciones

Características Generales

  • Estructura: JSON con event, data y sent_at
  • Confirmación: Responder HTTP 200, sino reintenta 3 veces en 24h
  • HTTPS: Recomendado para la URL de eventos
  • Evento principal: transaction.updated cuando cambia a estado final

Seguridad de Eventos

Wompi incluye un checksum en header X-Event-Checksum para verificar autenticidad.

Algoritmo de Verificación (SHA256):

1. Concatenar valores de signature.properties
2. Añadir timestamp del evento  
3. Añadir events_secret
4. Calcular SHA256 y comparar con checksum

Configuración en M&S

  1. En Wompi: Desarrolladores → URL de eventos
  2. URL: /wompi_payment_method/webhook/<secreto_opcional>
  3. Verificar acceso HTTPS desde internet
  4. Validar que events_secret coincida

Seguridad y Buenas Prácticas

Medidas de Seguridad Críticas

  • Claves privadas: Nunca expongas en frontend, solo en servidor
  • HTTPS obligatorio: Formulario de pago y webhook con SSL
  • Firma en servidor: Generar signature:integrity server-side
  • Ambiente correcto: No mezclar claves sandbox con producción
  • Logs activos: Registrar errores para diagnóstico
  • Actualizaciones: Mantener plugin actualizado

Prefijos de Claves por Ambiente

Ambiente URL Base Prefijos
Sandbox https://sandbox.wompi.co/v1 pub_test_, prv_test_, test_events_, test_integrity_
Producción https://production.wompi.co/v1 pub_prod_, prv_prod_, prod_events_, prod_integrity_

Pruebas y Verificación

Lista de Verificación

  1. Test de conexión: Usar test_connection() desde configuración
  2. Ambiente sandbox: Realizar transacciones de prueba con tarjetas test
  3. Firma de integridad: Verificar concatenación y secreto correcto
  4. Webhook funcional: Confirmar recepción de transaction.updated

Diagnóstico Automático

La función test_connection() valida:

  • ✅ Formato correcto de clave pública (prefijo pub_)
  • ✅ Configuración de integrity_secret y events_secret
  • ✅ Acceso al endpoint de enlaces de pago (si hay clave privada)
  • ✅ Coherencia entre ambiente y prefijos de claves

Solución de Problemas Comunes

Problema Causa y Solución
Invalid signature Causa: Firma signature:integrity incorrecta
Solución: Verificar concatenación: referencia + monto_centavos + moneda + integrity_secret. Usar secreto del ambiente correcto.
Redirección errónea Causa: URL redirect-url mal configurada
Solución: Revisar configuración del método de pago. Si está vacía, Wompi usa URL predeterminada + parámetro id.
Eventos no llegan Causa: Webhook mal configurado o bloqueado
Solución: Verificar URL en cuenta Wompi, usar HTTPS, responder HTTP 200, validar events_secret.
PENDING persistente Causa: Transacciones PSE/Nequi tardan minutos
Solución: Esperar evento transaction.updated. Revisar en plataforma Wompi si persiste.
Error 401 enlaces Causa: Clave privada inválida o ambiente incorrecto
Solución: Usar prv_test_ en sandbox, prv_prod_ en producción.
Monto mínimo no respetado Causa: Valor enviado menor al configurado
Solución: Verificar monto mínimo en configuración. Con pagos parciales, respetar mínimo aunque sea menor al saldo.
Prefijo clave incorrecto Causa: Mezclar claves de diferentes ambientes
Solución: Todas las claves deben tener mismo prefijo según ambiente (test_ o prod_).

Conclusión

Integración Completa

El plugin Wompi Payment Method para M&S CRM proporciona una integración robusta con la pasarela Wompi, permitiendo cobrar facturas mediante:

  • 🛒 Web Checkout (redirección)
  • 🔗 Enlaces de pago (API)

Puntos Clave para el Éxito

  • ✨ Comprender estructura de claves y secretos
  • 🔐 Generar correctamente firma de integridad
  • 📊 Manejar adecuadamente estados de transacciones
  • 🔔 Configurar apropiadamente webhook
  • 🧪 Probar siempre en ambiente sandbox
  • 🛡️ Proteger secretos y usar HTTPS

¡Listo para Producción!

Siguiendo esta documentación y las recomendaciones de Wompi, tendrás un proceso de cobro fiable y seguro. Podrás aceptar pagos en línea de manera fácil y profesional.

Volver al Inicio