Requisitos previos
Antes de dispersar pagos a empleados, es necesario:
Tener saldo disponible en el bolsillo correspondiente al tipo de pago (en este caso, bolsillo nómina)
Perfil de nómina creado (Ej: "Administrativo", "Desarrolladores", "Operativos")
Empleados registrados con información bancaria válida
Paso a Paso: Pago de Nómina
Paso 1: Recargar Bolsillo
Descripción: Este paso es fundamental para asegurar que existe saldo disponible en el bolsillo asignado antes de realizar la dispersión de nómina. Los bolsillos actúan como "cuentas virtuales" segregadas por tipo de pago, permitiendo control contable granular.
1.1 Recarga de Bolsillo con Saldo ePayco
Descripción: Transfiere fondos desde tu saldo principal de ePayco hacia el bolsillo de nómina. Este proceso requiere autenticación de dos factores (2FA) por seguridad.
Flujo 2FA/OTP:
Solicitar OTP: El sistema genera un código de un solo uso (OTP) y lo envía por SMS o correo electrónico
Validar OTP: El usuario debe ingresar el código recibido dentro del tiempo límite (30 segundos)
Token de sesión: Una vez validado, se genera un token de sesión temporal
Bloqueo por intentos: Después de 3 intentos fallidos, la operación se bloquea temporalmente
Validaciones automáticas:
Verificación de límite diario de recarga
Validación de saldo disponible en cuenta ePayco
Validación del OTP
Resultado: El bolsillo queda cargado con el monto especificado y se crea un registro de conciliación.
Paso 2: Crear Perfil de Nómina
Descripción: Los perfiles permiten segmentar a los empleados por departamento, rango salarial, o categoría laboral. Esto facilita la generación de reportes diferenciados y el control de costos por área.
Endpoint:
POST https://apiflow.epayco.io/payouts/api/v2/profiles
Content-Type: application/json
{
"id_epayco": 613711,
"name": "Atención al cliente",
"state": true,
"range_from": 1580000,
"range_to": 6580000,
"commerce_type": "C",
"plan_type": 1010,
"client_name": "default epayco"
}
Beneficios:
Reportes separados por área (ej: "Gasto total desarrolladores vs administrativos")
Control de rangos salariales permitidos
Facilita auditorías y análisis de costos
Paso 3: Registrar Empleados
Descripción: Antes de dispersar nómina, cada empleado debe estar registrado con su información bancaria completa.
Endpoint:
POST https://apiflow.epayco.io/payouts/api/v2/employees
Content-Type: application/json
{
"id_epayco": 123123,//<---cliente epayco id
"id_plan": 1010,
"document_type": "Cédula de ciudadanía",
"document_number": 1010101010,
"name": "juan guillermo",
"last_name": "suarez velasquez",
"email": "test@gmail.com",
"phone": 3101231212,
"url_image": "",
"bank": "BANCOLOMBIA",
"bank_type": "Ahorros",
"bank_number": "10101010101",
"contract_type": "Indefinido",
"start_contract": "2011-12-01T00:00:00.000Z",
"salary": 3000000,
"profile": "123123123123123",//id perfil
"state": true,
"private_label": 123,
"partner": 123,
"commerce_type": "C",
"full_name": "juan guillermo suarez velasquez"
}
Validaciones:
Número de cuenta válido según formato bancario
Tipo de documento correcto
Banco registrado en el catálogo
Asociación válida a un perfil activo
Paso 4: Crear Pagos de Nómina
Descripción: Con el bolsillo recargado y empleados registrados, procede a crear los pagos de nómina. Puedes crear pagos individuales o masivos .
4.1 Pago Individual
Endpoint:
POST https://apiflow.epayco.io/payouts/api/v2/payments/bulk
Content-Type: application/json
[
{
"id_epayco": 613711,
"private_label": 4877,
"partner": 0,
"commerce_type": "C",
"id_plan": 1010,
"type": "pago proveedor",
"type_payment": "saldo_epayco",
"franchise": "",
"state": "SIN_PROCESAR",
"source_id": null,
"source_type": "bolsillo",
"target_type": "proveedor",
"invoice_reference": "",
"pay_epayco_account": false,
"category": "Cultivo de cereales (excepto arroz), legumbres y semillas oleaginosas",
"environment": "production",
"id_pocket": 384,
"target_id": 1342,
"account_type": "Ahorros",
"target_document_number": 1020558,
"target_document_type": "Cédula de ciudadanía",
"client_name": "Diséño & Más S.A.S.",
"target": {
"id_epayco": 613711,
"client_name": "Diséño & Más S.A.S.",
"id_plan": 1010,
"name": "Diséño & Más S.A.S.",
"state": true,
"company_name": "certificacion",
"document_type": "Cédula de ciudadanía",
"document_number": "1010101010",
"email": "test@certificacion.com",
"phone": 3121212212,
"url_imagen": "",
"bank": "DAVIPLATA",
"type_account": "Ahorros",
"account_number": "3121212212",
"id_category": "0111",
"category": "Cultivo de cereales (excepto arroz), legumbres y semillas oleaginosas",
"commerce_type": "C",
"id_epayco_provider": 0,
"create_at": "2025-08-28T13:32:09.182Z",
"id_provider": 1339,
"updated_at": "2025-08-28T13:32:09.182Z",
},
"category_id": "0111",
"gross_total": 0,
"debs_total": 0,
"period_start": "2025-08-29 00:00:00",
"period_end": "2025-08-29 00:00:00",
"total": 10000,
"description": "",
"invoice": "N/A",
"note": [],
"value": "10000",
"callback_url": "https://miempresa.com/webhook/bulk-payment"
}]
Procesamiento automático:
Validación de destinatarios: El sistema verifica que cada empleado existe y está activo
Validación de perfil: Comprueba que el empleado tiene un perfil asignado
Validación de saldo: Verifica que el bolsillo tiene fondos suficientes
Cálculo de comisiones: Genera automáticamente las comisiones ePayco
Persistencia: Guarda los pagos en estado SIN PROCESAR en la base de datos
Step 5: Generar Dispersión (Procesamiento)
Descripción: Una vez creados los pagos, se deben procesar para enviarlos al banco. El sistema decide automáticamente si usa procesamiento individual o batch según la cantidad de pagos.
Endpoint:
Content-Type: application/json
{
"target": "proveedor",
"payments": [
{
"paymentId": "68ee6db37dcd1222c128c67f"
}
]
}
Paso 6: Monitoreo y Callbacks
Descripción: El sistema monitorea constantemente el estado de los pagos y notifica automáticamente a tu sistema mediante callbacks HTTP.
Estados de pago:
SIN PROCESAR: Pago creado, esperando procesamiento
PENDIENTE: En tránsito hacia el banco
ACEPTADO: Dispersión exitosa
RECHAZADO: El banco rechazó la transacción
FALLIDO: Error técnico en el procesamiento
Callback automático: El sistema envía un POST al callback_url configurado:
POST https://miempresa.com/webhook/payment-status
Content-Type: application/json
{
"data": {
"operationId": "69cb49054334fa678e786f4c",
"status": "FALLIDO",
"occurredAt": "2026-04-14T00:43:25.885Z",
"amount": 10000,
"currency": "COP",
"externalReference": null,
"reasonCode": "PAYMENT_ERROR",
"reasonMessage": "TypeError: Cannot read properties of undefined (reading 'message')"
}
}
Consulta manual de estado:
Content-Type: application/json
{
"id_payment": 2200
}