Servicios públicos

Esta página cubre los endpoints de Servicios públicos. Además de lo que se lista acá, cualquiera de ellos puede devolver los errores comunes: llave inválida, falta de x-idempotency, validación o límite de peticiones. Todas las rutas de /utilities responden 403 con {"message": "Company does not have this feature."} si tu empresa tiene apagado el módulo de servicios públicos. Viene activo por defecto; si lo ves, pídele a soporte que lo active.

El pago es asíncrono. POST /utilities responde 200 cuando OnePay pudo consultar la deuda y tu saldo alcanza; el pago al proveedor ocurre después, en segundo plano. Si el proveedor falla en ese paso, no recibes un error HTTP: lo ves en el status al consultar el pago. Mira Estados del pago después del 200.

Endpoints: Listar proveedores · Consultar deuda · Realizar pago · Consultar un pago · Crear link de pago · Crear link de domiciliación · Listar domiciliaciones · Listar pagos de domiciliaciones · Eliminar domiciliación por referencia y teléfono · Eliminar domiciliación por ID

Errores del proveedor de la factura

Para consultar o pagar una factura, OnePay le pregunta la deuda al proveedor del convenio. Si ese proveedor responde con un error, te llega uno de estos códigos. Salen tanto en consultar deuda como en realizar pago, porque el pago siempre consulta la deuda antes de crearse. Si el convenio tiene más de un proveedor habilitado, OnePay los intenta en orden y te devuelve el error del último.

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`22000` `bill_already_paid`	418	La factura ya ha sido pagada recientemente	El proveedor reporta que esa factura ya se pagó.	Confirma con tu cliente; no la vuelvas a cobrar.	No
`22001` `bill_cannot_be_paid`	400	La factura no puede ser pagada error interno	El proveedor rechazó la consulta o tiene problemas con el servicio de recaudo.	Intenta más tarde. Si sigue, escribe a soporte con la referencia.	Sí, más tarde
`22002` `bill_does_not_exist`	404	La factura no existe, o no se encuentra disponible en este momento	La referencia no existe en ese convenio, o el proveedor no respondió (caída, tiempo de espera, respuesta inesperada).	Revisa la referencia y el convenio. Si estás seguro de que son correctos, reintenta más tarde.	Sí, tras revisar la referencia
`22003` `bill_does_not_have_debt`	400	La factura no tiene deuda pendiente para pagar	La factura existe pero no tiene saldo por pagar.	No hay nada que cobrar hasta que el convenio emita una nueva factura.	No
`22004` `bill_does_not_have_provider`	404	La factura no tiene proveedor asignado	El convenio no tiene un proveedor habilitado para recaudar.	Escribe a soporte con el `provider_id`.	No
`22005` `bill_expired`	400	La factura ha expirado	El proveedor reporta la factura vencida, o respondió con un error que no tiene un código propio.	Confirma con tu cliente la fecha de vencimiento. Si no está vencida, escribe a soporte.	No
`22006` `bill_in_progress`	400	La factura ya se encuentra en proceso de pago	Hay un pago de esa factura en curso en el proveedor.	Vuelve a consultar la deuda en unos minutos. Antes de enviar otro `POST /utilities`, confirma el estado del pago anterior para no duplicarlo.	Solo la consulta
`22010` `not_founds`	404	No se encontraron resultados	El recaudador de OnePay no tiene cupo disponible en este momento. No es un problema de la factura.	Reintenta más tarde. Si persiste, escribe a soporte.	Sí, más tarde
`22012` `bill_try_latter`	400	Intente más tarde	El proveedor no está disponible temporalmente.	Reintenta con espera creciente (por ejemplo 1, 5 y 15 minutos).	Sí, con espera
`22013` `bill_unknown_error`	400	Error desconocido en la factura	El proveedor respondió con un código que OnePay no reconoce.	Reintenta más tarde. Si persiste, escribe a soporte con la referencia.	Sí, más tarde
`220016` `bill_amount_is_high`	400	El monto de la factura es mayor a 1.000.000 y no se puede pagar	La deuda es de COP 1.000.000 o más, el tope de este canal para el convenio.	Esta factura no se puede pagar por la API; tu cliente debe pagarla por otro canal.	No

Para decidir qué hacer, usa code_name y no el texto de message: el texto puede cambiar, el code_name no.

Listar proveedores

GET /utilities/providers · Referencia Este endpoint no tiene errores propios. Solo aplican los errores comunes.

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
Sin código	403	Company does not have this feature.	Tu empresa tiene apagado servicios públicos.	Pídele a soporte que lo active.	No

Consultar deuda

GET /utilities/providers/{provider}/{reference} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, BillService no existe	El `provider` no existe, está deshabilitado o fue retirado.	Vuelve a listar proveedores y usa un `id` vigente.	No
`10002` `record_not_found`	404	Registro no encontrado	El `provider` no es un UUID.	Envía el `id` tal como lo devuelve el listado.	No
Sin código	422	La referencia no puede ser menor a 3 caracteres	La referencia tiene menos de 3 caracteres.	Corrige la referencia.	Sí, tras corregir
Sin código	422	La referencia no puede ser mayor a 50 caracteres	La referencia tiene más de 50 caracteres.	Corrige la referencia.	Sí, tras corregir
`220xx`	400, 404, 418	Ver tabla	El proveedor de la factura respondió con un error.	Ver Errores del proveedor de la factura.	Según el código

Una deuda consultada con éxito queda guardada una hora: si consultas la misma referencia dentro de esa hora, recibes el mismo resultado sin volver a preguntarle al proveedor. Los errores no se guardan.

Realizar pago

POST /utilities · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10003` `idempotency_error`	409	No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency	Falta el header `x-idempotency`.	Envía un valor único por pago en `x-idempotency`.	Sí, con el header
`10001` `validation_error`	422	El campo provider id es obligatorio.	Falta `provider_id`, no es un UUID, o falta `reference`.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`10001` `validation_error`	422	El provider id seleccionado es inválido.	El convenio no existe, está deshabilitado o fue retirado.	Vuelve a listar proveedores.	Sí, tras corregir
`10001` `validation_error`	422	El campo external id no debe ser mayor que 255 caracteres.	`external_id` tiene más de 255 caracteres.	Acorta tu identificador.	Sí, tras corregir
`10803` `company_amount_limit`	422	La compañía no tiene fondos suficientes para realizar la operación	El saldo de tu empresa en OnePay es menor que la deuda de la factura.	Recarga tu saldo y vuelve a enviar el pago.	Sí, tras recargar
`220xx`	400, 404, 418	Ver tabla	El proveedor respondió con un error al consultar la deuda. El pago no se crea.	Ver Errores del proveedor de la factura.	Según el código

Un 200 no significa que la factura quedó pagada: significa que el pago quedó en cola. Antes de reintentar un pago que creíste fallido, consúltalo. Enviar otro POST con un x-idempotency nuevo crea un pago nuevo.

Estados del pago después del 200

El pago al proveedor corre en segundo plano. Consulta su status con GET /utilities/{payment_id}.

`status`	Qué significa	Qué hacer
`created`, `pending`	El pago está en cola para enviarse al proveedor.	Espera y vuelve a consultar.
`approved`, `confirmed`	El proveedor aceptó el pago. `paid_at` trae la fecha.	Nada: la factura quedó pagada.
`failed`	El último intento falló en el proveedor (rechazo, error del servicio). OnePay lo reintenta solo cada 14 minutos, hasta 50 veces.	No lo pagues de nuevo mientras siga en `failed`: puede pasar a `approved` en un reintento. Si sigue así después de un día, escribe a soporte con el `id`.
`expired`	El pago se cerró sin pagarse: la factura ya estaba pagada por otro registro, se retiró o venció.	Consulta la deuda de nuevo antes de crear otro pago.

Mientras el proveedor esté fuera de horario, la factura no aparezca o no tenga deuda, el pago se queda en su estado actual y OnePay lo sigue reintentando en el mismo ciclo.

Consultar un pago

GET /utilities/{payment_id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, BillPayment no existe	El `payment_id` no existe.	Usa el `id` que devolvió `POST /utilities`.	No
`10002` `record_not_found`	404	Registro no encontrado	El pago es de otra empresa, o el `payment_id` no es un UUID.	Usa un `id` de tu empresa, tal como lo devolvió la API.	No

Crear link de pago

POST /utilities/links · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10003` `idempotency_error`	409	No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency	Falta el header `x-idempotency`.	Envía un valor único por link.	Sí, con el header
`10001` `validation_error`	422	El campo reference es obligatorio.	Falta `reference`, `amount` o `redirect_url`, el monto está por debajo del mínimo de la moneda, o `redirect_url` no es una URL.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`10002` `record_not_found`	404	Registro no encontrado, BillService no existe	Tu empresa no tiene un convenio propio configurado en OnePay. Este endpoint es para empresas que recaudan sus propias facturas.	Escribe a soporte para configurar tu convenio.	No

Crear link de domiciliación

POST /utilities/direct-debits/link · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10003` `idempotency_error`	409	No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency	Falta el header `x-idempotency`.	Envía un valor único por link.	Sí, con el header
`10001` `validation_error`	422	El campo reference es obligatorio.	Falta `reference` o tiene más de 60 caracteres, `phone` no es un teléfono válido, `approx_amount` es negativo, o `expiration_minutes` está fuera de 60 a 43.200.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`10002` `record_not_found`	404	Registro no encontrado, BillService no existe	Tu empresa no tiene un convenio propio habilitado.	Escribe a soporte para configurar tu convenio.	No

Listar domiciliaciones

GET /utilities/direct-debits · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, BillService no existe	Tu empresa no tiene un convenio propio configurado.	Escribe a soporte para configurar tu convenio.	No
Sin código	400	Requested filter(s) `…` are not allowed. Allowed filter(s) are `document_number, payment_method_type, reference, status`.	Enviaste un `filter[...]` que no existe.	Usa solo los filtros de la lista.	Sí, tras corregir
Sin código	400	Requested sort(s) `…` is not allowed. Allowed sort(s) are `payment_method_type, created_at, updated_at, reference, phone, email, status`.	Enviaste un `sort` que no existe.	Usa solo los campos de la lista.	Sí, tras corregir

Listar pagos de domiciliaciones

GET /utilities/direct-debits/payments · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, BillService no existe	Tu empresa no tiene un convenio propio configurado.	Escribe a soporte para configurar tu convenio.	No
Sin código	400	Requested filter(s) `…` are not allowed. Allowed filter(s) are `reference, status, bill_id, amount_in_cents, paid_at`.	Enviaste un `filter[...]` que no existe.	Usa solo los filtros de la lista.	Sí, tras corregir
Sin código	400	Requested sort(s) `…` is not allowed. Allowed sort(s) are `amount_in_cents, status, created_at, paid_at`.	Enviaste un `sort` que no existe.	Usa solo los campos de la lista.	Sí, tras corregir
Sin código	500	Server Error	`filter[paid_at]` no es una fecha que se pueda leer.	Envía la fecha en formato `AAAA-MM-DD`.	Sí, tras corregir

Eliminar domiciliación por referencia y teléfono

DELETE /utilities/direct-debits · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	El campo reference es obligatorio. (y 1 error más)	Falta `reference` o `phone`, o `phone` no es un teléfono válido.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`10002` `record_not_found`	404	Registro no encontrado, BillService no existe	Tu empresa no tiene un convenio propio configurado.	Escribe a soporte para configurar tu convenio.	No
`10002` `record_not_found`	404	Registro no encontrado, Bill no existe	No hay una domiciliación activa con esa referencia y ese teléfono en tu convenio, o ya se eliminó.	Revisa la referencia y el teléfono con listar domiciliaciones.	No

Eliminar domiciliación por ID

DELETE /utilities/direct-debits/{bill_id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, Bill no existe	El `bill_id` no existe o la domiciliación ya se eliminó.	Usa un `id` de listar domiciliaciones.	No
`10002` `record_not_found`	404	Registro no encontrado	La domiciliación es de un convenio de otra empresa, o el `bill_id` no es un UUID.	Usa un `id` de tu convenio.	No

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Errores del proveedor de la factura

Listar proveedores

Consultar deuda

Realizar pago

Estados del pago después del 200

Consultar un pago

Crear link de pago

Crear link de domiciliación

Listar domiciliaciones

Listar pagos de domiciliaciones

Eliminar domiciliación por referencia y teléfono

Eliminar domiciliación por ID

​Errores del proveedor de la factura

​Listar proveedores

​Consultar deuda

​Realizar pago

​Estados del pago después del 200

​Consultar un pago

​Crear link de pago

​Crear link de domiciliación

​Listar domiciliaciones

​Listar pagos de domiciliaciones

​Eliminar domiciliación por referencia y teléfono

​Eliminar domiciliación por ID

Errores del proveedor de la factura

Listar proveedores

Consultar deuda

Realizar pago

Estados del pago después del 200

Consultar un pago

Crear link de pago

Crear link de domiciliación

Listar domiciliaciones

Listar pagos de domiciliaciones

Eliminar domiciliación por referencia y teléfono

Eliminar domiciliación por ID