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. Filtros Avanzados (opcional)

Dentro del formulario de configuración encontrarás una sección llamada "Filtros Avanzados", plegada por defecto. Haz clic en su título para expandirla. Estos filtros controlan qué facturas y conceptos puede ver y cobrar Palomma. Si no configuras ninguno, la pasarela solo mostrará facturas pendientes ya emitidas.

Recomendación: Si eres nuevo con Palomma, deja los Filtros Avanzados desactivados hasta que el flujo básico esté funcionando correctamente. Una vez confirmado, puedes habilitarlos según las necesidades de tu inmobiliaria.

🔑 Paso 5. 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 6. 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.

Los Filtros Avanzados son opciones adicionales que controlan exactamente qué facturas y conceptos puede ver y cobrar Palomma cuando un arrendatario consulta sus pendientes en el portal de clientes. Todos están desactivados por defecto.

¿Cómo acceder? Dentro del formulario de configuración de Palomma, haz clic en el encabezado de la sección «Filtros Avanzados» para expandirla. La sección aparece plegada por defecto.

🔲 Filtro 1. ¿Incluir facturas en borrador?

¿Qué hace? Cuando está activo, las facturas que ya existen en el sistema pero aún no han sido enviadas a la DIAN (estado «borrador») también aparecen como pendientes de pago en el portal de clientes.

¿Qué se genera al pagar una factura en borrador?

1. Se registra el pago de la factura.
2. Se genera el recibo de caja.
3. El envío a la DIAN ocurre según el filtro «¿Enviar automáticamente a la DIAN?»: si está activo, se envía de inmediato; si no, queda pendiente para envío manual.

Importante: Si activas este filtro, asegúrate de revisar tus borradores periódicamente. Si hay borradores con errores o que no deberían cobrarse aún, el arrendatario podría pagarlos antes de que los corrijas.

📋 Filtro 2. Resoluciones

¿Qué hace? Permite limitar qué facturas y conceptos son visibles en el portal de clientes según la resolución de facturación a la que pertenecen.

¿Cómo funciona el filtro por tipo de tercero? Para cada resolución seleccionada, el sistema también filtra los conceptos según el tipo de tercero configurado en esa resolución (inquilino o propietario). Esto garantiza que un inquilino solo vea los conceptos que le corresponden y un propietario vea los suyos.

Caso de uso típico: Si manejas varias resoluciones (por ejemplo, una para arriendos residenciales y otra para locales comerciales) y solo quieres habilitar el pago en línea para residenciales, selecciona únicamente esa resolución.

🔲 Filtro 3. ¿Permitir pagar conceptos que no aplican a una factura?

¿Qué hace? Habilita el cobro de conceptos que no generan factura, sino solo un recibo de caja (por ejemplo, depósitos de garantía, ajustes manuales, cobros por administración, etc.).

¿Qué se genera al pagar este tipo de concepto?

• Se genera solo el recibo de caja. No se crea ninguna factura.
• El pago queda registrado en el sistema con la Forma de Pago configurada en Palomma.

🔲 Filtro 4. ¿Permitir pagar conceptos de periodos futuros?

¿Qué hace? Permite que los arrendatarios paguen anticipadamente conceptos de periodos que todavía no han iniciado (por ejemplo, pagar en abril el canon de mayo).

Consideraciones importantes:

• Aplica solo a conceptos, tanto facturables como no facturables. Nunca se muestran facturas de periodos futuros directamente.
• Si el concepto futuro genera factura, esa factura se crea automáticamente en el momento del pago y queda registrada como pagada.
• Si el concepto futuro no genera factura, se genera solo el recibo de caja (siempre que el Filtro 3 esté activo, o bien si el concepto no requiere factura por su naturaleza).

Dependencia: Al activar este filtro se habilita el campo «Rango de conceptos futuros» (Filtro 5). Es obligatorio configurarlo para definir hasta cuántos meses hacia adelante se mostrarán los conceptos.

📅 Filtro 5. Rango de conceptos futuros

¿Qué hace? Define hasta qué mes futuro puede ver y pagar el arrendatario. Este campo solo está disponible cuando el Filtro 4 está activo.

Nota sobre el rango: El rango cubre el mes calendario completo. Por ejemplo, con «Tres meses» y hoy siendo 15 de abril, el límite es el 31 de julio (no el 15 de julio). Si seleccionas «Sin límite», ten en cuenta que podrían mostrarse conceptos muy lejanos si tienes contratos con cargos programados a futuro.

Dependencia requerida: Este campo está deshabilitado si el Filtro 4 («¿Permitir pagar conceptos de periodos futuros?») no está activo. Debe activarse primero ese filtro para poder configurar el rango.

🔲 Filtro 6. ¿Incluir los intereses de mora en la factura del canon?

¿Qué hace? Cuando está activo, los intereses de mora que tenga pendientes un arrendatario se adjuntan como detalle adicional a la factura del canon a la que corresponden, y se cobran juntos en un solo pago.

¿Qué se genera al pagar el canon con interés incluido?

1. Se registra el pago del canon.
2. Se genera automáticamente la factura del interés de mora (si aún no existía) y queda como pagada.
3. Se genera un recibo de caja que incluye tanto el canon como el interés.
4. El envío de la factura de interés a la DIAN sigue la regla del filtro «¿Enviar automáticamente a la DIAN?».

¿Qué pasa si el interés no tiene canon asociado? Si un interés de mora no encuentra una factura de canon pendiente a la cual adjuntarse (por ejemplo, el canon ya fue pagado pero el interés quedó pendiente), se cobrará de forma independiente como ítem separado en el portal.

📦 Filtro 7. ¿Agrupar conceptos pertenecientes al mismo periodo?

¿Qué hace? Cuando está activo, los conceptos que comparten el mismo contrato, el mismo tercero y el mismo rango de fechas del periodo se muestran al arrendatario como un único ítem pagable, cuyo valor a pagar es la suma de todos ellos. Al pagarlo, se genera un solo recibo de caja y, cuando corresponda, una sola factura agrupada por contrato.

Reglas de agrupación:

• Se agrupan los conceptos con el mismo contrato, el mismo tercero (deudor) y el mismo periodo (fechas de inicio y fin idénticas).
• Si en el periodo ya existe una factura pendiente del mismo contrato y tercero, los conceptos no facturables se adjuntan a esa factura (el saldo de la factura suma esos conceptos).
• Los conceptos facturables (que al pagarse generan factura) se agrupan entre sí, pero nunca se adjuntan a una factura pendiente existente: al pagarlos se crea una nueva factura agrupada por contrato.
• Los conceptos con valor negativo (descuentos o notas crédito del periodo) se descuentan del grupo, pero solo si existe un concepto positivo del mismo periodo con saldo suficiente. Si un descuento no encuentra un concepto positivo que lo absorba, se omite del ítem agrupado (no aparecerá en el portal) para evitar saldos negativos.

Dependencia requerida: Este filtro está deshabilitado hasta que se active al menos uno de estos dos filtros: «¿Permitir pagar conceptos que no aplican a una factura?» (Filtro 3) o «¿Permitir pagar conceptos de periodos futuros?» (Filtro 4). La razón es que solo tiene sentido agrupar conceptos cuando hay conceptos sueltos visibles en el portal.

¿Cuándo conviene activarlo? Si tu inmobiliaria suele facturar al arrendatario varios conceptos del mismo periodo (canon + administración + servicios + cuotas) y prefieres que el arrendatario los pague de forma consolidada (un solo recibo, una sola factura), activa este filtro. Si prefieres que el arrendatario decida qué conceptos pagar individualmente, déjalo desactivado.

🔲 Filtro 8. ¿Enviar automáticamente a la DIAN?

¿Qué hace? Cuando está activo, nuby envía automáticamente a la DIAN las facturas que se paguen o generen a través de Palomma y que requieran envío (facturas en borrador, facturas de conceptos futuros, facturas de intereses de mora).

¿Qué pasa si el envío a la DIAN falla?

• El pago siempre queda registrado, independientemente del resultado del envío a la DIAN.
• La factura queda marcada como «pagada, pendiente de envío a la DIAN».
• Puedes reintentar el envío manualmente desde el módulo de Facturación.

Dependencia requerida: Este campo está deshabilitado hasta que se active al menos uno de estos tres filtros: «¿Incluir facturas en borrador?», «¿Permitir pagar conceptos de periodos futuros?» o «¿Incluir los intereses de mora en la factura del canon?». La razón es que el envío automático solo tiene efecto cuando alguno de esos filtros puede generar o pagar facturas que aún no han sido enviadas a la DIAN.

📊 Resumen de dependencias entre filtros

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, debes copiar y proporcionar al equipo de Palomma tus credenciales de conexión, quienes se encargarán de realizar la configuración directamente en su portal.

Asegúrate de enviarles la siguiente información:

• Dominio de la instancia de nuby: Es la URL o enlace desde el cual ingresas habitualmente al sistema.

• Client ID: Visible en el formulario de configuración de Palomma dentro de nuby.

• Secret Key: Visible en el formulario de configuración de Palomma dentro de nuby.

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. (Opcional) Expande la sección "Filtros Avanzados" para personalizar qué facturas y conceptos puede ver Palomma.

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

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

8. Copia las credenciales OAuth2 generadas.

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

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

🔹 Reglas clave:

AV Villas es una entidad bancaria colombiana que ofrece un servicio de recaudo empresarial, es decir, permite que tus clientes (arrendatarios, propietarios, etc.) realicen pagos directamente desde sus cuentas bancarias hacia la cuenta de tu empresa.

Al integrar AV Villas con nuby, el sistema podrá:

🔹 Funcionalidades de la integración:

• Recaudo empresarial automatizado → Recibe pagos de manera automática a través del banco.

• Débito automático a cuentas bancarias → Tus arrendatarios pueden pagar directamente desde sus cuentas.

• Integración con sistema bancario colombiano → Conectado al ecosistema financiero colombiano.

• Autenticación segura mediante OAuth 2.0 → Comunicación encriptada y protegida entre nuby y el banco.

🔹 Beneficios para tu inmobiliaria:

• Registro contable automático → Los pagos recibidos se registran automáticamente con la forma de pago y cuenta contable que configures.

• Reducción de trabajo manual → No necesitas registrar cada pago manualmente en el sistema.

• Conciliación bancaria simplificada → Al tener una forma de pago exclusiva para AV Villas, podrás identificar fácilmente estos pagos en tus reportes.

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

• Administradores del sistema → Para configurar la pasarela y habilitar el recaudo a través de AV Villas.

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

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

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

📌 Requisito 1. Convenio de recaudo con el Banco AV Villas

Debes tener un acuerdo firmado con el Banco AV Villas para el servicio de recaudo empresarial. Si aún no lo tienes, contacta a tu ejecutivo comercial del banco para iniciar el proceso.

📌 Requisito 2. NURA (Número Único de Recaudo)

El banco te proporcionará un código numérico que identifica a tu empresa de manera única en su sistema de recaudos.

• Ejemplo de formato → 00028848

• Dónde obtenerlo → Se lo entrega el banco al momento de firmar el convenio de recaudo empresarial. Si ya tienes un convenio pero no recuerdas el NURA, solicítalo a tu ejecutivo de cuenta en AV Villas.

📌 Requisito 3. Credenciales de conexión (API)

El área técnica o de integraciones del banco te proporcionará los siguientes datos de conexión:

• Authorization (Basic Auth) → Código de seguridad principal para la conexión.

• X-Authorization → Código de seguridad adicional requerido por AV Villas.

• Grant Type → Método de autenticación (generalmente "Client Credentials").

• Scope → Permisos de la conexión (generalmente payment_mgmt/sesskey_payment).

Importante: Si no cuentas con el NURA o las credenciales de conexión, debes solicitarlos al Banco AV Villas antes de continuar. Sin estos datos, no es posible completar la configuración.

📌 Requisito 4. 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 contablemente los pagos que lleguen a través de AV Villas.

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: "Recaudo AV Villas".

3. Asígnale la cuenta contable que corresponda según tu plan de cuentas (la cuenta bancaria de AV Villas donde se depositan los recaudos).

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 5. 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 (barra superior), haz clic en el ícono de "Herramientas" (el cuarto ícono de la barra de herramientas).

2. En el menú desplegable que aparece, haz clic en "Configuraciones".

📌 Paso 3. Ingresa al módulo de Pasarelas de Pago

Dentro de la pantalla de Configuraciones, busca y haz clic en la opción "Integración con Pasarelas de Pago". La descripción indica: "Configure las pasarelas de pago disponibles para procesar transacciones en línea desde el portal de clientes."

📄 Paso 4. 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: AV Villas, EnLineaPagos (ELP), PayU Latam.

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

• Estado → Un indicador que muestra si la pasarela está Activa (etiqueta verde) o Inactiva (etiqueta roja).

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

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

• Enlace "Sitio Web" → Lleva a la página oficial del proveedor de pagos.

Además, en el menú lateral izquierdo verás la lista de todas las pasarelas disponibles con su ícono. Un punto verde junto al nombre indica que la pasarela está activa.

Nota: Puedes tener múltiples pasarelas activas simultáneamente (por ejemplo, AV Villas y PayU). Cada una opera de forma independiente.

📄 Paso 5. Selecciona AV Villas

Tienes dos opciones para llegar a la pantalla de configuración:

• Opción A: Ubica la tarjeta de AV Villas y haz clic en el botón "Configurar".

• Opción B: En el menú lateral izquierdo, haz clic directamente sobre el ícono de AV Villas.

Ambas opciones te llevarán a la misma página de configuración.

Una vez dentro del formulario de configuración de AV Villas, verás una pantalla dividida en dos áreas:

• Área izquierda (formulario) → Donde ingresas los datos de configuración.

• Área derecha (panel informativo) → Muestra una descripción de la pasarela, sus características y un enlace al sitio web del banco.

A continuación te explicamos cada campo del formulario y cómo completarlo:

⚙️ Paso 1. Activar o desactivar AV Villas

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

Recomendación: Completa primero todos los campos del formulario y luego activa el interruptor. De esta forma evitarás errores de validación al guardar.

💰 Paso 2. Seleccionar la Forma de Pago

Selecciona de la lista desplegable la Forma de Pago que quieres usar para registrar contablemente los pagos recibidos a través de AV Villas.

• Obligatorio → Este campo es requerido cuando la pasarela está activada.

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

• Ejemplo → Consignación (11100501 - BANCOLOMBIA)

🔹 ¿Qué Forma de Pago seleccionar?

Escoge la opción que corresponda a la cuenta bancaria donde AV Villas deposita los recaudos. Te recomendamos crear una forma de pago exclusiva para esta pasarela. Esto te permitirá:

• Identificar fácilmente los pagos recibidos por esta vía 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 "Recaudo AV Villas" y asígnale la cuenta contable que corresponda a tu cuenta bancaria en AV Villas.

Atención: Si la lista aparece vacía, significa que no hay formas de pago configuradas con cuenta contable en el sistema. Primero debes crear o editar una forma de pago desde el módulo de Contabilidad y asignarle una cuenta PUC.

🔢 Paso 3. Ingresar el NURA (Número Único de Recaudo)

Escribe el NURA que te proporcionó el Banco AV Villas.

• Obligatorio → Este campo es requerido cuando la pasarela está activada.

• Ejemplo → 00028848

Atención: Escribe el número exactamente como te lo proporcionó el banco, incluyendo los ceros a la izquierda si los tiene. No agregues espacios, guiones ni caracteres especiales. Solo ingresa los números.

🔑 Paso 4. Ingresar el Authorization (Basic Auth)

Pega en este campo el código de autorización proporcionado por el área técnica del banco.

• Obligatorio → Este campo es requerido cuando la pasarela está activada.

• Formato esperado → Basic dXN1YXJpbzpjbGF2ZTEyMw==

• Campo protegido → El texto se muestra oculto (con puntos o asteriscos) por seguridad. Si necesitas verificar lo que escribiste, haz clic en el ícono del ojo (👁) que aparece al lado derecho del campo para mostrar temporalmente el texto.

Seguridad: Este dato es confidencial. No lo compartas con terceros ni lo envíes por canales inseguros como correos electrónicos sin cifrar o mensajes de texto.

⚙️ Paso 5. Seleccionar el Grant Type

Selecciona de la lista desplegable el método de autenticación que el sistema usará para conectarse con los servidores de AV Villas.

Nota: Si no estás seguro, deja la opción por defecto (Client Credentials). En la mayoría de los casos, es la configuración correcta.

📋 Paso 6. Configurar el Scope

Este campo define los permisos o el alcance de las operaciones que el sistema puede realizar a través de la conexión con AV Villas.

• Obligatorio → Este campo es requerido cuando la pasarela está activada.

• Valor por defecto → payment_mgmt/sesskey_payment (ya viene preconfigurado).

Consejo: En la mayoría de los casos no es necesario modificar este campo. Solo cámbialo si el banco te indica expresamente un valor diferente.

🔐 Paso 7. Ingresar el X-Authorization

Pega en este campo el segundo código de seguridad proporcionado por el Banco AV Villas.

• Obligatorio → Este campo es requerido cuando la pasarela está activada.

• Campo protegido → Al igual que el Authorization, el texto se muestra oculto por seguridad. Usa el ícono del ojo (👁) si necesitas verificar lo que ingresaste.

Seguridad: Al igual que el campo Authorization, este dato es confidencial. Manéjalo con las mismas precauciones de seguridad.

🌐 Paso 8. Seleccionar el Entorno

Determina si la pasarela operará en modo de pruebas o en modo de producción (transacciones reales con dinero real).

Advertencia: No selecciones Producción hasta estar completamente seguro de que la configuración es correcta. En modo Producción, las transacciones involucran dinero real y no se pueden revertir fácilmente.

💾 Paso 9. Guardar la configuración

Haz clic en el botón "Guardar Configuración" ubicado en la parte inferior del formulario.

Si la pasarela está desactivada:

• Se guardan los campos que hayas completado. Los campos no obligatorios pueden quedar vacíos.

• AV Villas no procesará pagos.

Si la pasarela está activada:

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

• Si falta algún campo, verás un mensaje de error rojo indicando cuál campo necesitas completar.

• Si todo está correcto, verás un mensaje de éxito verde: "Configuración de AV Villas guardada correctamente."

Atención: Si recibes un error al guardar indicando que un campo es "requerido", asegúrate de haber completado todos los campos del formulario antes de intentar guardar nuevamente.

Para una configuración exitosa, sigue estos pasos en orden:

1. Verifica que tienes todos los datos del banco a la mano (NURA, Authorization, X-Authorization, Scope, Grant Type).

2. Verifica que existe una Forma de Pago configurada con cuenta contable en el sistema. Si no la tienes, créala primero desde Configuración > Contabilidad > Formas de Pago.

3. Ingresa al módulo Pasarelas de Pago y selecciona AV Villas.

4. Completa todos los campos del formulario (deja el Entorno en Pruebas (TEST) por ahora).

5. Activa el interruptor "¿Habilitar AV Villas?".

6. Haz clic en "Guardar Configuración".

7. Realiza una transacción de prueba para verificar que la conexión funciona correctamente.

8. Si todo funciona, cambia el Entorno a Producción (PRODUCTION) y guarda nuevamente.

Consejo: Es recomendable completar primero todos los campos (paso 4) y después activar el interruptor (paso 5), ya que al activar la pasarela todos los campos se vuelven obligatorios. De esta manera evitarás mensajes de error por campos vacíos.

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

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

📋 Checklist de configuración

¿Puedo guardar la configuración sin activar la pasarela?

Sí. Si dejas el interruptor "¿Habilitar AV Villas?" apagado, puedes guardar los datos que ya tengas disponibles sin que los demás campos sean obligatorios. Esto es útil si quieres ir ingresando la información a medida que el banco te la proporciona.

¿Qué pasa si no aparecen opciones en la lista de Forma de Pago?

Significa que no hay formas de pago configuradas con una cuenta contable asociada en el sistema. Debes:

1. Ir al módulo de Contabilidad.

2. Crear o editar una Forma de Pago.

3. Asignarle una cuenta contable (PUC) que corresponda a la cuenta bancaria de AV Villas.

4. Volver al módulo de Pasarelas de Pago para seleccionarla.

¿Puedo cambiar la configuración después de activar la pasarela?

Sí. Puedes modificar cualquier campo en cualquier momento. Solo recuerda hacer clic en "Guardar Configuración" después de realizar cambios.

¿Qué sucede si ingreso datos incorrectos?

Si los datos de conexión (NURA, Authorization, X-Authorization) son incorrectos, el sistema no podrá comunicarse con el banco y los pagos no se procesarán. En la mayoría de los casos recibirás un mensaje de error. Verifica los datos con el banco y corríjelos.

¿Puedo desactivar la pasarela temporalmente?

Sí. Simplemente apaga el interruptor "¿Habilitar AV Villas?" y guarda. La configuración se conservará y podrás reactivarla en cualquier momento sin necesidad de volver a ingresar todos los datos.

¿Puedo tener AV Villas y otras pasarelas activas al mismo tiempo?

Sí. Puedes tener múltiples pasarelas activas simultáneamente (por ejemplo, AV Villas, PayU y EnLineaPagos). Cada una opera de forma independiente con sus propias credenciales y configuración.

¿Necesito conocimientos técnicos para completar esta configuración?

No. Solo necesitas ingresar los datos que te proporciona el banco en los campos correspondientes. Sin embargo, si tienes dudas sobre los datos técnicos (Authorization, X-Authorization, Grant Type, Scope), contacta al área de soporte técnico del Banco AV Villas o al equipo de soporte de nuby.

Los campos aparecen en gris y no puedo editarlos, ¿qué hago?

Esto significa que tu usuario no tiene permisos para modificar la configuración de pasarelas de pago. Solicita al administrador del sistema que te asigne los permisos de edición necesarios en el módulo de Pasarelas de Pago.

¿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.

Para configurar AV Villas en nuby, sigue estos pasos:

1. Verifica que tienes todos los datos del banco: NURA, Authorization, X-Authorization.

2. Verifica que tienes una Forma de Pago con cuenta contable configurada.

3. Ve a Herramientas > Configuraciones > Integración con Pasarelas de Pago.

4. Haz clic en "Configurar" en la tarjeta de AV Villas.

5. Completa todos los campos del formulario (deja el Entorno en TEST).

6. Activa el interruptor "¿Habilitar AV Villas?".

7. Haz clic en "Guardar Configuración".

8. Realiza pruebas para verificar que todo funciona.

9. Cambia el Entorno a Producción (PRODUCTION) y guarda nuevamente.

10. ¡Listo! Tu sistema ya puede recibir pagos a través de AV Villas.

🔹 Reglas clave: