🛠️ Cómo Construir una Integración de Pagos Personalizada
Si eres desarrollador y quieres conectar tu propia pasarela de pago al ecosistema de CRMHUB, esta guía explica cómo construir un proveedor de pagos personalizado compatible con checkouts, suscripciones y métodos de pago guardados en todas las subcuentas.
🧩 Componentes Principales
App del Marketplace: el contenedor de tu integración, con OAuth, permisos (scopes) y páginas personalizadas.
Proveedor de Pagos Personalizado: la configuración que declara qué tipos de pago soportas.
queryUrl: el endpoint de tu backend que maneja las operaciones del lado del servidor (verificación, reembolsos, gestión de suscripciones).
paymentsUrl: la URL pública del iframe de checkout donde el cliente paga.
Página personalizada: la interfaz donde el usuario ingresa sus claves API y credenciales.
🛠️ Pasos de Integración
Paso 1: Crea tu App en el Marketplace
Configura los permisos OAuth necesarios (pagos/órdenes, suscripciones, transacciones, proveedor personalizado, productos), la URL de redirección tras la autenticación, tus claves de cliente (guardadas de forma segura en tu backend), la URL de webhook para eventos de instalación/desinstalación y la clave SSO para desencriptar los tokens de autenticación.
Paso 2: Autenticación e Instalación
Intercambia el código de OAuth por tokens de acceso y crea la configuración pública del proveedor vía API con nombre, descripción, logo, queryUrl y paymentsUrl. Gestiona los webhooks del ciclo de vida de la app.
Paso 3: Configuración de Prueba y Producción
Los usuarios ingresan sus credenciales a través de tu página personalizada. Llama al API de configuración de conexión para guardar las claves de prueba y producción, y define tu proveedor como predeterminado en Pagos > Integraciones.
Paso 4: Implementación del iFrame de Checkout
Secuencia de eventos:
Emite custom_provider_ready cuando el iframe carga.
Recibe payment_initiate_props con los detalles del pago.
Procesa el pago y emite una respuesta de éxito, error o cancelación.
CRMHUB llama a tu endpoint verify para confirmar la transacción.
La respuesta de éxito debe incluir el chargeId de tu pasarela; la de error, un mensaje visible para el usuario; y el endpoint de verificación debe devolver el estado (exitoso, fallido o pendiente).
Paso 5: Métodos de Pago Guardados y Suscripciones
Declara addCardOnFileSupported: true en el evento ready.
Maneja setup_initiate_props para guardar tarjetas.
Implementa en tu queryUrl los endpoints: list_payment_methods (métodos guardados de un contacto), charge_payment (cobrar un método guardado fuera de sesión), create_subscription y cancel_subscription.
Paso 6: Reembolsos
Gestiona las solicitudes de tipo "refund" con monto, transactionId y chargeId. Soporta reembolsos parciales.
Paso 7: Webhooks
Envía webhooks al endpoint de CRMHUB para eventos de suscripción (en periodo de prueba, activa, actualizada, cobrada) y eventos de pago (capturado), incluyendo un snapshot con estado, montos y marcas de tiempo.
⚠️ Notas Importantes
Responsabilidad del ciclo de cobro: los proveedores personalizados deben gestionar sus propios ciclos de facturación, cobrar a los clientes y notificar a CRMHUB vía webhooks.
La verificación es la fuente de verdad: la respuesta de verify, no los webhooks, es lo que establece inicialmente el estado de una suscripción.
Cualquier lenguaje: puedes usar cualquier lenguaje que soporte peticiones HTTP y JSON.
Modo de prueba disponible: simula pagos en sandbox antes de salir a producción.
💡 Buenas Prácticas
Registra (log) todas las peticiones a tu queryUrl, webhooks y respuestas de API para facilitar la depuración.
Usa todos los identificadores disponibles (transactionId, chargeId, subscriptionId) para conciliar pagos.
Implementa un manejo de errores y monitoreo robusto.
Prueba los flujos de principio a fin en modo de prueba antes de lanzar a producción.