Saltar al contenido principal

🔌 Integraciones

Las Integraciones permiten conectar UnoPago con servicios externos para ampliar funcionalidades y automatizar procesos.

Integraciones Disponibles​

💳 Stripe​

¿Qué es Stripe?

Stripe es una plataforma de pagos internacionales que permite a tu institución recibir pagos con tarjetas de crédito/débito desde cualquier parte del mundo.

¿Para qué sirve?

  • Recibir pagos internacionales
  • Aceptar tarjetas Visa, Mastercard, Amex
  • Pagos recurrentes automáticos
  • Mayor alcance para familias en el extranjero

Configurar Stripe​

Paso 1: Crear cuenta en Stripe​
  1. Ve a stripe.com
  2. Crea una cuenta para tu institución
  3. Completa el proceso de verificación
  4. Activa tu cuenta
Paso 2: Obtener credenciales​

En tu dashboard de Stripe:

  1. Ve a Developers → API Keys
  2. Copia tu Publishable Key (clave pública)
  3. Copia tu Secret Key (clave secreta)
Seguridad

La Secret Key es confidencial. No la compartas ni la expongas públicamente.

Paso 3: Configurar en UnoPago​
  1. Configuración → Integraciones → Stripe
  2. Haz clic en "Configurar"
  3. Pega tus credenciales:
    • Publishable Key
    • Secret Key
  4. Selecciona el modo:
    • Test → Para pruebas
    • Live → Para producción
  5. Guarda
Paso 4: Activar​
  • Marca como "Activo"
  • Los representantes verán la opción de pagar con tarjeta
  • Las transacciones se procesarán a través de Stripe

Comisiones de Stripe​

Stripe cobra comisiones por transacción:

  • Aprox. 2.9% + $0.30 por transacción en USA
  • Varía por país y tipo de tarjeta

¿Quién paga la comisión?

Puedes:

  • Absorber el costo institucionalmente
  • Trasladarlo al representante (agregarlo al monto)
  • Configurar en Pagos y Órdenes → Método Stripe → Comisión

🏦 Banco Mercantil (C2P)​

¿Qué es la integración C2P?

Conexión directa con Banco Mercantil para procesar pagos móviles Comercio a Persona de forma automática.

Beneficios:

  • Confirmación inmediata de pagos
  • Sin verificación manual
  • Experiencia fluida para representantes
  • Menos errores humanos

Configurar Banco Mercantil C2P​

Requisitos previos​
  1. Tener cuenta empresarial en Banco Mercantil
  2. Contratar el servicio C2P con el banco
  3. Obtener credenciales de la API
Paso 1: Contactar al banco​
  1. Llama a tu ejecutivo de Banco Mercantil
  2. Solicita activar "Pago Móvil C2P"
  3. El banco te proporcionará:
    • ID de Comercio
    • Clave API
    • URLs de endpoints
Paso 2: Configurar en UnoPago​
  1. Configuración → Integraciones → Banco Mercantil
  2. Haz clic en "Configurar"
  3. Ingresa los datos:
    • ID de Comercio
    • Clave API
    • Cuenta asociada
  4. Modo (Test o Producción)
  5. Guarda
Paso 3: Probar​
  • Realiza pagos de prueba
  • Verifica que se confirmen automáticamente
  • Monitorea el panel para ver transacciones en tiempo real

Solución de problemas C2P​

"Error de conexión"

  • Verifica credenciales
  • Confirma con el banco que el servicio esté activo
  • Revisa que la cuenta tenga fondos suficientes para el servicio

"Pagos no se confirman automáticamente"

  • Revisa la configuración de webhooks
  • Verifica que los endpoints estén accesibles
  • Contacta a soporte de UnoPago

🔔 Webhooks​

¿Qué son los webhooks?

Son notificaciones automáticas que UnoPago envía a tu servidor cuando ocurren eventos importantes.

¿Para qué sirven?

  • Integrar UnoPago con tu sistema contable
  • Automatizar procesos internos
  • Sincronizar datos en tiempo real
  • Notificar a otros sistemas

Eventos disponibles​

Pagos:

  • payment.created → Nuevo pago reportado
  • payment.verified → Pago verificado y aprobado
  • payment.rejected → Pago rechazado

Órdenes:

  • order.created → Nueva orden generada
  • order.paid → Orden pagada completamente
  • order.overdue → Orden vencida

Clientes:

  • client.created → Nuevo cliente registrado
  • client.updated → Datos de cliente actualizados

Configurar Webhooks​

Paso 1: Preparar tu endpoint​

Necesitas un servidor que reciba las notificaciones:

URL ejemplo:

https://tu-servidor.com/webhooks/unopago

Tu endpoint debe:

  • Estar accesible públicamente (HTTPS)
  • Responder con código 200 OK
  • Procesar el payload JSON
Paso 2: Configurar en UnoPago​
  1. Configuración → Integraciones → Webhooks
  2. Haz clic en [+ Agregar Webhook]
  3. Ingresa:
    • URL de tu endpoint
    • Eventos que quieres recibir (selecciona)
    • Secret (para verificar autenticidad)
  4. Guarda
Paso 3: Probar​
  • UnoPago enviará un evento de prueba
  • Verifica que tu servidor lo reciba
  • Confirma que el procesamiento funcione

Ejemplo de payload​

{
  "event": "payment.verified",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "payment_id": "pay_12345",
    "order_id": "ord_67890",
    "client_id": "cli_11111",
    "amount": 100.00,
    "currency": "USD",
    "method": "zelle",
    "reference": "REF123456",
    "status": "verified"
  }
}

Seguridad de webhooks​

Verificar autenticidad:

Cada webhook incluye una firma en el header:

X-UnoPago-Signature: sha256=...

Verifica esta firma usando el secret compartido para asegurar que la notificación viene de UnoPago.

📧 Integración con Email (SMTP)​

Usar tu propio servidor de email:

Si prefieres enviar notificaciones desde tu dominio:

  1. Configuración → Integraciones → SMTP
  2. Configura:
    • Servidor SMTP
    • Puerto
    • Usuario
    • Contraseña
    • Email remitente
  3. Prueba el envío
  4. Activa

Beneficios:

  • Emails desde @tuinstitución.edu
  • Mayor control
  • Mejor deliverability

💬 WhatsApp Business API​

Para instituciones con alto volumen:

Si envías muchas notificaciones, puedes integrar WhatsApp Business API oficial:

  1. Solicita acceso a Meta (Facebook)
  2. Obtén credenciales de API
  3. Configura en UnoPago
  4. Usa plantillas aprobadas por Meta

Nota: Requiere aprobación de Meta y tiene costos asociados.

Mejores Prácticas​

✅ Prueba en modo Test primero​

Todas las integraciones ofrecen modo de prueba:

  • Stripe tiene Test Mode
  • Mercantil tiene ambiente de sandbox
  • Webhooks pueden probarse con herramientas como webhook.site

🔒 Protege tus credenciales​

  • Nunca compartas API keys públicamente
  • Usa variables de entorno
  • Rota las claves periódicamente

📊 Monitorea las integraciones​

Revisa regularmente:

  • Logs de errores
  • Transacciones fallidas
  • Webhooks no entregados

🔄 Mantén actualizadas​

  • Verifica cambios en las APIs externas
  • Actualiza credenciales cuando sea necesario
  • Lee release notes de los servicios

Preguntas Frecuentes​

¿Las integraciones tienen costo adicional?​

Los servicios externos (Stripe, WhatsApp Business API) sí tienen costos propios. La integración en UnoPago no tiene costo extra.

¿Qué pasa si Stripe falla?​

Los representantes verán un error y pueden usar otros métodos de pago disponibles.

¿Puedo desactivar una integración temporalmente?​

Sí, simplemente desmarca "Activo" en la configuración.

¿Los webhooks son obligatorios?​

No, solo si necesitas integrar con sistemas externos.

¿Qué soporte técnico hay para integraciones?​

Contacta al equipo de soporte de UnoPago para asistencia con cualquier integración.

Próximos pasos​

Con las integraciones configuradas, tu sistema está completo. Revisa:

Las integraciones expanden las capacidades de UnoPago. ¡Configúralas según tus necesidades! 🔌