¿Cómo configurar la pasarela Palomma en nuby? [BETA]

Palomma es una plataforma de pagos moderna diseñada para Latinoamérica que permite a los negocios recibir dinero de manera escalable y eficiente. Al integrarla con nuby, tus arrendatarios podrán pagar sus facturas directamente desde el portal de clientes sin necesidad de acercarse a una oficina o realizar transferencias manuales.

🔹 Métodos de pago disponibles:

• PSE → Transferencia bancaria directa desde cualquier banco colombiano.

• Nequi → Billetera digital de Bancolombia.

• Daviplata → Billetera digital de Davivienda.

• Tarjetas de crédito y débito → Visa, Mastercard, American Express.

🔹 Beneficios de usar Palomma:

• Pagos en tiempo real → Los pagos se registran automáticamente en nuby.

• Múltiples métodos de pago → Tus clientes eligen el método que prefieran.

• Notificaciones automáticas → nuby recibe confirmación del pago al instante (vía webhooks).

• Registro contable automático → Se genera el recibo de pago y el documento contable sin intervención manual.

• Disponible en Colombia → Integrada con el ecosistema financiero colombiano.

🔹 ¿Para quién es útil esta guía?

• Administradores del sistema → Para configurar la pasarela y habilitar los pagos electrónicos.

• Gerencia → Para entender el impacto y los beneficios de la integración.

• Contabilidad y Tesorería → Para comprender cómo se registran los pagos recibidos a través de Palomma.

Antes de configurar Palomma en nuby, verifica que cuentas con lo siguiente:

📌 Requisito 1. Cuenta activa en Palomma

Debes tener un convenio vigente con Palomma. Si aún no tienes cuenta, puedes registrarte en su sitio web palomma.com o contactar a tu representante comercial.

📌 Requisito 2. ID de Inmobiliaria

Palomma te proporcionará un identificador único para tu inmobiliaria. Es un código corto que identifica a tu empresa dentro de la plataforma de Palomma.

• Ejemplo de formato → tuespacioideal, inmobiliariaxyz

• Dónde obtenerlo → Desde el panel de administración de Palomma o solicitándolo a su equipo de soporte.

📌 Requisito 3. Forma de Pago configurada en nuby

Necesitas tener al menos una Forma de Pago activa en nuby con una cuenta contable asignada. Esta forma de pago se usará para registrar los pagos que lleguen a través de Palomma.

Si aún no tienes una forma de pago específica, te recomendamos crearla antes de continuar:

1. Ve a Configuración > Contabilidad > Formas de Pago.

2. Crea una nueva forma de pago con un nombre descriptivo, por ejemplo: "Pago Electrónico - Palomma".

3. Asígnale la cuenta contable que corresponda según tu plan de cuentas.

Importante: Solo aparecerán en el selector aquellas formas de pago que tengan una cuenta contable asociada. Si no ves opciones disponibles, revisa que tus formas de pago tengan la cuenta contable configurada.

📌 Requisito 4. Permisos de administrador

• Necesitas permisos de visualización en el módulo de Pasarelas de Pago para ver la configuración.

• Necesitas permisos de edición en el módulo de Pasarelas de Pago para poder modificar y guardar la configuración.

Tip: Si no tienes acceso al módulo, solicita al usuario administrador de tu sistema que te otorgue los permisos necesarios.

🔐 Paso 1. Inicia sesión en nuby

Ingresa a nuby con tu usuario y contraseña habituales.

📂 Paso 2. Dirígete a Configuraciones

1. En el menú principal, busca y haz clic en "Configuraciones".

2. Dentro de las configuraciones, busca la opción "Pasarelas de Pago".

📌 Paso 3. Visualiza las pasarelas disponibles

Al ingresar al módulo verás una pantalla de bienvenida donde se listan todas las pasarelas disponibles en formato de tarjetas. Cada tarjeta muestra:

• Nombre de la pasarela → Por ejemplo: Palomma, PayU, ELP.

• Descripción → Qué hace y qué métodos de pago soporta.

• Estado → Un indicador que muestra si la pasarela está Activa o Inactiva.

• Características → Lista de funcionalidades de la pasarela.

• Botón "Configurar" → Para acceder al formulario de configuración.

Nota: Puedes tener múltiples pasarelas activas simultáneamente (por ejemplo, Palomma y PayU). Tus arrendatarios podrán elegir su método de pago preferido al momento de pagar.

📄 Paso 4. Selecciona Palomma

Ubica la tarjeta de Palomma y haz clic en el botón "Configurar". También puedes acceder desde el menú lateral izquierdo, donde verás la opción "Palomma" listada junto con las demás pasarelas.

Una vez dentro del formulario de configuración de Palomma, verás los siguientes campos. A continuación te explicamos cada uno y cómo completarlos:

⚙️ Paso 1. Activar o desactivar Palomma

El primer campo es un interruptor (toggle) con la etiqueta "¿Habilitar Palomma?".

Recomendación: Completa primero los campos obligatorios (ID de Inmobiliaria y Forma de Pago) y luego activa el interruptor. De esta forma evitarás errores de validación al guardar.

🏢 Paso 2. Ingresar el ID de Inmobiliaria en Palomma

Escribe el identificador único de tu inmobiliaria, proporcionado por Palomma.

• Etiqueta roja "Obligatorio" → Este campo es requerido cuando la pasarela está activa.

• Ejemplo → tuespacioideal

• ¿Por qué es importante? → Este ID le permite a Palomma saber a qué inmobiliaria corresponde cada transacción de pago.

Atención: Este ID debe coincidir exactamente con el que está registrado en tu cuenta de Palomma. Si hay algún error, los pagos no se procesarán correctamente.

💰 Paso 3. Seleccionar la Forma de Pago

Selecciona del listado la Forma de Pago que quieres usar para registrar los pagos recibidos a través de Palomma.

• Etiqueta roja "Obligatorio" → Este campo es requerido cuando la pasarela está activa.

• Formato de las opciones → Se muestran como: Nombre de la forma de pago (código cuenta - nombre cuenta).

🔹 ¿Qué pasa cuando un arrendatario paga a través de Palomma?

1. Palomma notifica a nuby que el pago fue exitoso.

2. nuby registra automáticamente el pago asociándolo a la Forma de Pago que seleccionaste aquí.

3. Se genera el recibo de pago y el documento contable correspondiente.

4. Se actualiza el saldo de la factura del arrendatario.

🔹 ¿Qué Forma de Pago seleccionar?

Te recomendamos crear una forma de pago exclusiva para Palomma. Esto te permitirá:

• Identificar fácilmente los pagos electrónicos en tus reportes.

• Facilitar la conciliación bancaria.

• Tener claridad en las auditorías contables.

Sugerencia: Si aún no tienes una forma de pago específica, créala desde Configuración > Contabilidad > Formas de Pago con nombre "Pago Electrónico - Palomma" y asígnale la cuenta contable que corresponda.

🔑 Paso 4. Campos OAuth2 (solo lectura)

Verás dos campos adicionales con la etiqueta azul "Solo Lectura":

• ID del Cliente OAuth2 → Identificador generado automáticamente por nuby.

• Secret Key del Cliente OAuth2 → Clave secreta generada automáticamente por nuby.

No necesitas ingresar nada en estos campos. El sistema los genera automáticamente cuando activas la pasarela y guardas la configuración por primera vez.

💾 Paso 5. Guardar la configuración

Haz clic en el botón "Guardar Configuración".

Si la pasarela está desactivada:

• Se guardan los campos que hayas completado. Los campos OAuth2 permanecen vacíos.

• Palomma no aparecerá como opción de pago para tus arrendatarios.

Si la pasarela está activada:

• El sistema valida que los campos obligatorios estén completos.

• Si es la primera vez, se generan automáticamente las credenciales OAuth2.

• Verás un mensaje de confirmación: "Configuración de Palomma guardada correctamente."

Atención: Si recibes un error al guardar indicando que un campo es "requerido", asegúrate de haber completado el ID de Inmobiliaria y seleccionado una Forma de Pago.

Después de guardar la configuración en nuby con la pasarela activada, debes completar la integración desde el lado de Palomma. Para ello, necesitarás las credenciales OAuth2 que nuby generó automáticamente.

Próximamente

Esta tabla resume todos los campos disponibles en el formulario de configuración de Palomma:

Una vez configurada la integración, este es el flujo que ocurre cuando un arrendatario paga una factura a través de Palomma:

1. El arrendatario ingresa al portal de clientes de nuby y selecciona la factura que desea pagar.

2. Elige Palomma como método de pago entre las opciones disponibles.

3. Es redirigido al checkout seguro de Palomma, donde selecciona su método preferido (PSE, Nequi, Daviplata o tarjeta).

4. Palomma procesa el pago con la entidad financiera correspondiente.

5. El banco confirma la transacción y Palomma recibe la respuesta.

6. Palomma notifica a nuby mediante un webhook que incluye las credenciales OAuth2.

7. nuby valida la autenticidad de la notificación y registra el pago automáticamente:

   • Registra el pago de la factura.

   • Genera el recibo de pago.

   • Crea el documento contable.

   • Actualiza el saldo de la factura.

8. El arrendatario recibe confirmación del pago exitoso.

🔹 Seguridad de la comunicación

Las credenciales OAuth2 (Client ID y Client Secret) garantizan que las notificaciones de pago entre Palomma y nuby sean auténticas y seguras:

• Cada notificación de Palomma incluye estas credenciales.

• nuby valida que la notificación sea legítima antes de registrar el pago.

• Esto previene fraudes y notificaciones falsas de pago.

Antes de dar por terminada la configuración, verifica los siguientes puntos:

📋 Checklist en nuby

📋 Checklist en el portal de Palomma

¿Puedo guardar la configuración sin completar todos los campos?

Sí, pero depende del estado del interruptor:

• Si el interruptor está desactivado: puedes guardar con campos vacíos sin problema.

• Si el interruptor está activado: el ID de Inmobiliaria y la Forma de Pago son obligatorios.

¿Puedo tener Palomma y otras pasarelas activas al mismo tiempo?

Sí. Puedes tener múltiples pasarelas activas simultáneamente (por ejemplo, Palomma, PayU y ELP). Tus arrendatarios verán todas las opciones disponibles al momento de pagar y podrán elegir la que prefieran.

¿Qué pasa si cambio el ID de Inmobiliaria después de recibir pagos?

• Los pagos anteriores no se ven afectados (ya fueron procesados).

• Los nuevos pagos usarán el nuevo ID.

• Importante: Asegúrate de que el nuevo ID también esté configurado en el portal de Palomma.

¿Puedo cambiar la Forma de Pago después de recibir pagos?

Sí. El cambio solo afecta a los pagos futuros. Los pagos anteriores mantienen la forma de pago que estaba configurada al momento de recibirlos.

¿Las credenciales OAuth2 cambian si desactivo y reactivo Palomma?

No. Las credenciales se generan una sola vez y se mantienen permanentemente, sin importar cuántas veces desactives o reactives la pasarela. Solo se regeneran si se elimina manualmente el registro del cliente OAuth.

¿Por qué los campos OAuth2 están vacíos si la pasarela está activa?

Posibles causas:

• No guardaste la configuración después de activar la pasarela. Haz clic en "Guardar Configuración".

• Hubo un error al generar las credenciales. Intenta desactivar, guardar, reactivar y guardar nuevamente.

• Las credenciales fueron eliminadas de forma manual. En este caso, desactiva y reactiva la pasarela para regenerarlas.

¿Cómo sé si un pago fue registrado correctamente?

Cuando un pago se registra correctamente a través de Palomma, ocurre lo siguiente:

• Se genera el pago de la factura.

• Se genera el recibo de caja.

• Se genera el documento contable.

• La factura actualiza su saldo.

• Si el saldo queda en cero, la factura cambia a estado pagada.

• Se crea un registro de transacción visible en el área de clientes.

¿Cómo regenero las credenciales OAuth2 si fueron comprometidas?

Si sospechas que las credenciales fueron expuestas:

1. Ve a Configuraciones > API en nuby.

2. Ubica el cliente OAuth de Palomma y elimínalo.

3. Regresa al formulario de Pasarelas de Pago y guarda la configuración nuevamente con la pasarela activa.

4. Se generarán nuevas credenciales.

5. Actualiza las nuevas credenciales en el portal de Palomma.

Atención: Después de regenerar las credenciales, debes actualizar los valores en el portal de Palomma inmediatamente. De lo contrario, los webhooks de pago dejarán de funcionar.

Para configurar Palomma en nuby, sigue estos pasos:

1. Ve a Configuraciones > Pasarelas de Pago.

2. Haz clic en "Configurar" en la tarjeta de Palomma.

3. Ingresa el ID de Inmobiliaria proporcionado por Palomma.

4. Selecciona la Forma de Pago con la que se registrarán los pagos.

5. Activa el interruptor "¿Habilitar Palomma?".

6. Haz clic en "Guardar Configuración" → Se generan las credenciales OAuth2.

7. Copia las credenciales OAuth2 generadas.

8. Ingresa al portal de Palomma y configura las credenciales y la URL de webhook.

9. ¡Listo! Tus arrendatarios ya pueden pagar a través de Palomma.

🔹 Reglas clave: