Diferencias con Nómina
Los pagos a proveedores siguen el mismo flujo base que nómina, con las siguientes diferencias:
No requieren perfil: Los proveedores no se agrupan por perfiles
Información adicional: Los proveedores tienen campos adicionales como company_name, category, type_account
Paso a Paso: Pago a Proveedores
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: Registrar Proveedores
Descripción: Registra cada proveedor con su información fiscal y bancaria.
Endpoint:
POST https://apiflow.epayco.io/payouts/api/v2/providers
Content-Type: application/json
{
"id_epayco": 613711,
"client_name": "Almacén Paola",
"id_plan": 1010,
"name": "Nombre 23057",
"state": true,
"company_name": "Mikesoft sa",
"document_type": "Cedula de ciudadanía",
"document_number": "1231234",
"email": "mike10030@hotmail.com",
"phone": 994757867,
"url_imagen": "",
"bank": "BANCAMIA",
"type_account": "Ahorros",
"account_number": "12341234",
"id_category": "0112",
"category": "Cultivo de arroz",
"commerce_type": "P",
"id_epayco_provider": 0
}
Campos específicos de proveedores:
company_name: Razón social del proveedor
category: Clasificación del proveedor (ej: "Tecnología", "Servicios", "Suministros")
type_account: Tipo de cuenta bancaria (generalmente "CORRIENTE" para empresas)
Paso 3: Crear Pago a Proveedor
Descripción: Con el bolsillo recargado y proveedores registrados, procede a crear los pagos de proveedor . 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
}