1. Contexto inicial: ¿Qué es Payflow?#

Ejemplo práctico:#

El objetivo es que el empleado tenga un porcentaje de su salario disponible, no el 100% del mismo.

En este orden de ideas, para que una compañía que contrató la plataforma de Payflow pueda prestar correctamente el servicio de salario bajo demanda a sus empleados, es necesario que:

1.

Mantenga actualizada de manera diaria la información básica necesaria a nivel empleados: altas, bajas y modificaciones

2.

Consuma la información de pagos (también de manera diaria) para que la compañía pueda reportarla en su sistema de nómina y realizar los pagos.

2. Payflow: El Producto#

Aplicación móvil para empleados:#

Panel web para administradores#

API Pública de Payflow#

3. Objetivo de la integración#

4. Arquitectura#

1. Flujo de sincronización de empleados (POST /employees).

Este endpoint de nuestra API funciona como un método POST + PUT a pesar de que solo hagas POST:

1.

Crea empleados

2.

Actualiza empleados (datos y estado)

2. Flujo de sincronización de pagos (GET /payments).

Este endpoint de nuestra API disponibiliza las transacciones hechas en Payflow por los empleados de tu empresa.

5. Flujo de sincronización de empleados#

Para que un colaborador pueda usar la plataforma de Payflow, tiene que ser en primer lugar dado de alta: es decir, debe de ser creado como un potencial usuario por su empresa en su panel de control de Payflow.

El objetivo de este flujo es garantizar que solo los empleados correctos puedan usar Payflow y que sus datos estén actualizados.

Es importante recordar que Payflow es una plataforma provista por el empleador y el colaborador no puede modificar ningún dato allí. En caso de querer cambiar algo tiene que ir a su empleador y que este haga la modificación en el HR software, luego esta integración sincronizará los cambios en Payflow. Esto evita fraudes y garantiza la correcta prestación del servicio.

5.1 Información a sincronizar desde su HR software hacia su Panel de control de Payflow#

5.1.1 Campos de los empleados a sincronizar#

5.1.2 Entidades bancarias soportadas (campo bankEntity)#

5.1.3 Estados del empleado y reglas de negocio (campo status)#

5.2 Proceso técnico de sincronización, método y endpoint a usar#

Estándar operativo:

Envía las actualizaciones de todos los empleados de forma masiva usando el método POST (en batches de máximo 500 idealmente) y el endpoint /employees.

Nuestra API es capaz de tomar una petición por segundo desde una misma IP, no más que esto porque nuestro firewall te puede bloquear.

Frecuencia sugerida: 1 - 2 veces al día (si tienes >1000 empleados) o cada 4 - 8 horas (si tienes <1000 empleados). Esto es totalmente parametrizable.

Evita errores comunes:

Envía todos los datos obligatorios.

No uses salario = 0 para inactivar, usar siempre el campo status.

No dejes de enviar empleados para inactivar, usar siempre el campo status.

Envía nombres y apellidos completos

Tips técnicos:

Maneja errores 503 con retries y backoff.

Asegura que tu sistema aguante el volumen: CPU, memoria, timeouts.

Documenta las reglas clave para tu equipo: salarios y estados.

0. Cumplir con los prerrequisitos:

Acceso al Panel de control de Payflow - el equipo te dará el acceso.

La URL base y los endpoints:

Ambiente de pruebas:

URL base: https://api-public.payflow-dev.net

endpoint a usar: https://api-public.payflow-dev.net/employees

Producción:

URL base: https://api-public.payflow.es

endpoint a usar: https://api-public.payflow.es/employees

La API key.

Esta la puedes generar en el panel de control siguiendo estos pasos:

1.

Entra al apartado "integraciones" —> "integraciones"

2.

Selecciona API Payflow

3.

Dale al botón "Generar API Key"

4.

Guarda en un lugar seguro la API Key para poder usarla en la integración

Puedes volver acá para generar una nueva cuando quieras

En postman se vería así:

1. Extraer los datos necesarios de los empleados del HR software.

2. Ajustar estos datos en el formato JSON aceptado por la API de Payflow (máximo batches de 500 empleados por envío).

Ejemplo del JSON a enviar (batch de 5 empleados)

[
    {
        "firstName": "Test User", 
        "lastName": "Prueba Uno", 
        "payrollId": "PRUEBAPAYROLLID10000", 
        "personalId": "10238794004", 
        "documentType": "C_CIUDADANIA", 
        "email": "test_user_colombia1989@payflow.com", 
        "phone": "3209355001", 
        "bankAccountNumber": "3209355001", 
        "bankEntity": "Nequi",
        "bankAccountType": "savings",
        "address": "Edificio Lievano, Calle 11",
        "grossSalary": 20000000,
        "startDate": "2022-01-01",
        "contractEnd": "2050-01-01",
        "subsidiary": "900717898-1",
        "status": "active"
    },
    {
        "firstName": "Prueba",
        "lastName": "Prueba Dos",
        "payrollId": "PRUEBAPAYROLLID10001",
        "personalId": "10230090000",
        "documentType": "C_CIUDADANIA",
        "email": "test_user_colombia4252@payflow.com",
        "phone": "3128987763",
        "bankAccountNumber": "204230294838",
        "bankEntity": "BBVA",
        "bankAccountType": "savings",
        "address": "Edificio Lievano, Calle 11",
        "grossSalary": 20000000,
        "startDate": "2018-01-01",
        "contractEnd": "2050-01-01",
        "subsidiary": "900717898-1",
        "status": "active"
    },
    {
        "firstName": "Test User",
        "lastName": "Prueba Tres",
        "payrollId": "PRUEBAPAYROLLID10002",
        "personalId": "10230094576",
        "documentType": "C_CIUDADANIA",
        "email": "test_user_colombia19630@payflow.com",
        "phone": "3209355003",
        "bankAccountNumber": "22969294838",
        "bankEntity": "Lulo Bank",
        "bankAccountType": "savings",
        "address": "Edificio Lievano, Calle 11",
        "grossSalary": 55000000,
        "startDate": "2000-01-01",
        "contractEnd": "2050-01-01",
        "subsidiary": "900717898-1",
        "status": "active"
    },
    {
        "firstName": "Test User",
        "lastName": "Prueba Cuatro",
        "payrollId": "PRUEBAPAYROLLID10003",
        "personalId": "10238700577",
        "documentType": "C_CIUDADANIA",
        "email": "test_user_colombia19550@payflow.com",
        "phone": "3209355004",
        "bankAccountNumber": "29983849909",
        "bankEntity": "Bancolombia",
        "bankAccountType": "savings",
        "address": "Edificio Lievano, Calle 11",
        "grossSalary": 60000000,
        "startDate": "1999-01-01",
        "contractEnd": "2050-01-01",
        "subsidiary": "900717898-1",
        "status": "active"
    },
    {
        "firstName": "Test User",
        "lastName": "Prueba Cinco",
        "payrollId": "PRUEBAPAYROLLID10004",
        "personalId": "10238004578",
        "documentType": "C_CIUDADANIA",
        "email": "test_user_colombia3119@payflow.co",
        "phone": "3209355005",
        "bankAccountNumber": "27469294838",
        "bankEntity": "Colpatria",
        "bankAccountType": "savings",
        "address": "Edificio Lievano, Calle 11",
        "grossSalary": 100000000,
        "startDate": "2022-01-02",
        "contractEnd": "2050-01-01",
        "subsidiary": "900717898-1",
        "status": "active"
} 
]

En postman se vería así

3. Utilizar el método POST apuntando al endpoint /employees de la API de Payflow con estos batches de máximo 500 empleados.

6. Flujo de sincronización de pagos#

Para la preparación de la nómina de los colaboradores, es necesario que los pagos realizados en la plataforma de Payflow sean registrados en el software de nómina correctamente para su deducción de la nómina del periodo.

El objetivo de este flujo es garantizar que las transacciones realizadas en Payflow sean descontadas de la nómina de los empleados.

Hay que tener en cuenta que aunque la nómina se pague a final de mes o de la quincena, puede suceder que se paguen liquidaciones/finiquitos durante los períodos a colaboradores que se retiran. En estos casos se necesitará considerar y descontar las transacciones hechas en la plataforma de Payflow.

6.1 Información a sincronizar desde su Panel de control de Payflow hacia su HR software#

6.1.1 Campos de las transacciones a sincronizar#

6.1.2 Estados de las transacciones en Payflow (campo status)#

La API solo te mostrará los estados processed y processing pero te dejamos el detalle para que conozcas los demás

6.1.3 Parámetros opcionales (van en los headers de la consulta)#

La API te mostrará todas las transacciones, con status = processed o processing una a una, que se han hecho en tu empresa al menos que uses parámetros en los headers para filtrarlas.

paid

Booleano para mostrar solo las transacciones que se han/o no se han pagado

paid = true - te trae las transacciones pagadas hasta el momento

paid = false - te trae las transacciones no pagadas hasta el momento

En postman se vería así:

convoluted

Booleano que muestra la suma de las transacciones junto con el transaction id para cada empleado de la empresa.

convoluted = true - te trae la suma de transacciones con sus id's por empleado

convoluted = false - te trae las transacciones una a una

En postman se vería así:

Y el JSON de la respuesta de la API Payflow se vería así:

{
    "data": [
        {
            "ids": [
                "luqmR001",
                "aaa4Fc2e28"
            ],
            "user": "1023765879",
            "userPayrollId": "abc39485",
            "amount": 130000,
            "fee": 0,
            "informedToIntegration": false,
            "paid": true,
            "firstTransactionRequestedAt": "2025-01-24T00:00:00.000Z",
            "lastTransactionRequestedAt": "2025-01-28T14:28:29.000Z",
            "TransactionPaidAt": "2025-01-24T00:00:00.000Z",
            "lastTransactionPaidAt": "2025-01-28T14:28:29.000Z"
        },
        {
            "ids": [
                "aaa4Fc2e23",
                "aaa4Fc2e29"
            ],
            "user": "1098764900",
            "userPayrollId": "abc39489",
            "amount": 10000,
            "fee": 0,
            "informedToIntegration": false,
            "paid": true,
            "firstTransactionRequestedAt": "2025-01-24T00:00:00.000Z",
            "lastTransactionRequestedAt": "2025-02-03T13:41:55.000Z",
            "TransactionPaidAt": "2025-01-24T00:00:00.000Z",
            "lastTransactionPaidAt": "2025-02-03T13:41:55.000Z"
        }
    ]
}

start

Fecha desde la cual comienza la búsqueda en formato AAAA-MM-DD

Si la combinas con end puedes obtener las transacciones entre días específicos.

En postman se vería así:

end

Fecha hasta la cual finaliza la búsqueda en formato AAAA-MM-DD

Si la combinas con start puedes obtener las transacciones entre días específicos.

En postman se vería así:

cycle

Fecha del ciclo de pago formato YYYY-MM

En postman se vería así:

6.2 Información a sincronizar desde su HR software hacia su Panel de control de Payflow (opcional pero recomendado)#

6.2.1 Llamada acknowledge payments#

6.3 Proceso técnico de sincronización, método y endpoint(s) a usar#

Estándar operativo:

Realiza las consultas de las transacciones de los empleados usando el método GET y el endpoint /payments

Utiliza el id de cada transacción para identificarla en tu sistema para que no se dupliquen transacciones.

Todos los pagos En Proceso y Procesados deben ser recogidos e incorporados como novedad en la nómina; ya que los pagos En Proceso ya están en manos del banco receptor y pasarán a ser procesados en el corto plazo.

Si decides implementar el acknowledge payments, debes usar el método PUT y el endpoint /payments/acknowledge

Frecuencia sugerida: 1 - 2 veces al día (si tienes >1000 empleados) o cada 4 - 8 horas (si tienes <1000 empleados). Esto es totalmente parametrizable.

Evita errores comunes:

Antes de construir este flujo, asegúrate de que existe un concepto en la nómina de tu empresa a donde deban llegar las transacciones de Payflow para ser descontadas.

Tips técnicos:

Asegura que tu sistema aguante el volumen: CPU, memoria, timeouts.

0. Cumplir con los prerrequisitos:

Concepto de nómina creado en el HR Software para hacer los descuentos de transacciones Payflow, usualmente lo llaman "Anticipo Payflow"

Acceso al Panel de control de Payflow - el equipo te dará el acceso.

La URL base y los endpoints:

Ambiente de pruebas:

URL base: https://api-public.payflow-dev.net

endpoint a usar: https://api-public.payflow-dev.net/payments

Producción:

URL base: https://api-public.payflow.es

endpoint a usar: https://api-public.payflow.es/payments

La API key es la misma que generaste para el flujo de empleados

Definir si usarás algún parámetro para filtrar las transacciones desde la API de Payflow

1. Utilizar el método GET para extraer los datos de las transacciones desde Payflow.

Ejemplo del JSON que se obtiene del endpoint

{
    "data": [
        {
            "id": "aaa4Fc2e271",
            "user": "1022142724",
            "userPayrollId": "37112",
            "amount": 10000,
            "fee": 0,
            "status": "processed",
            "paid": true,
            "requestedAt": "2025-11-07T17:03:00.000Z",
            "paidAt": "2025-11-07T17:03:00.000Z",
            "message": null,
            "informedToIntegration": false
        },
        {
            "id": "Xcdmr6ooo9",
            "user": "1022142724",
            "userPayrollId": "37112",
            "amount": 5000,
            "fee": 0,
            "status": "processed",
            "paid": true,
            "requestedAt": "2025-11-21T09:17:00.000Z",
            "paidAt": "2025-11-21T09:17:00.000Z",
            "message": null,
            "informedToIntegration": false
        }
    ]
}

En postman se vería así

2. Tomar los datos necesarios de la respuesta de la API de Payflow para incorporarlos al HR Software en el concepto de nómina destinado para las transacciones Payflow.

Los datos necesarios van a variar dependiendo del HR Software y sus requerimientos para crear una novedad de nómina, pero usualmente se toman por lo menos:

id para identificar la transacción y evitar duplicados

user y/o userPayrollId para identificar al empleado al que se le hará el descuento

amount para poner en el concepto el monto a descontar

3. (Opcional pero recomendado) Utilizar el método PUT apuntando al endpoint /payments/acknowledge de la API de Payflow para marcar las transacciones informadas al HR Software.

Este endpoint permite cambiar el valor de la variable informedToIntegration de false (valor por defecto) a true.

Ambiente de pruebas:

URL base: https://api-public.payflow-dev.net

endpoint a usar: https://api-public.payflow-dev.net/payments/acknowledge

Producción:

URL base: https://api-public.payflow.es

endpoint a usar: https://api-public.payflow.es/payments/acknowledge

Ejemplo del JSON que se debe enviar en el body del request

{
    "paymentsToMarkAsInformed": [
        "aaa4Fc2e1",
        "aaa4Fc2e2",
        "aaa4Fc2e3"
    ]
}

Ejemplo del JSON que se obtiene del endpoint

{
    "paymentsMarked": [
        "aaa4Fc2e1",
        "aaa4Fc2e2",
        "aaa4Fc2e3"
    ]
}

Una vez marcadas todas las transacciones informadas, en el siguiente consumo del endpoint /payments verás la variable informedToIntegration=true en las transacciones que enviaste en este paso.

7. Paso a paso de la integración#

Acá te acompañaremos en cada paso y estaremos dispuestos a agendar sesiones de trabajo contigo y tu equipo para resolver cualquier duda! Los pasos para implementar esta integración son:

Ver cantidad total de empleados tanto en el HR Software como en el panel de control de Payflow (la manera más fácil es descargarlos en excel desde "ver empleados" en el panel de control de Payflow y hacer estos chequeos en excel).

Ver esa cantidad separada por sociedades en caso de que trabajemos con más de 1 entidad legal, ver que estas coinciden.

Ordenar la columna 'Salario neto' de Menor a Mayor. Revisar tanto los salarios más bajos, como los altos, para corroborar que la info se envió correctamente y no hay datos raros como 0s, negativos, números extremadamente altos, etc.

Revisar 5 personas en particular y de manera aleatoria para controlar que la información es correcta: Nombre, salario, datos bancarios completos, estado y número identificatorio fiscal de la entidad legal a la que están vinculados.

8. Monitoreo inicial#

Siempre es una buena práctica generar algún tipo de monitoreo de lo que está sucediendo en la integración.

9. Troubleshooting#

URL API desarrollo: https://api-public.payflow-dev.net/
Dashboard desarrollo: https://dashboard.payflow-dev.net/auth/login

URL API Producción: https://api-public.payflow.es/
Dashboard Producción: https://admin.payflow.es/auth/login