Colombia

Available schemes

Scheme	Description	Years
`ordinario`	Full employee: salud, pension, ARL, parafiscales, retencion	2025,2026
`integral`	Salario integral (>= 13 SMMLV): retencion, aportes sobre 70%	2025, 2026

Supported pay periods

`period.type`	Supported	Proration model
`monthly`	Yes	`split_monthly`
`biweekly`	Yes	`split_monthly`
`weekly`	No — `422 PERIOD_TYPE_NOT_SUPPORTED`	—

Applies to ordinario and integral. Under split_monthly the dependency graph runs over the monthly figures and the result is split afterwards, so every bracket, floor and ceiling is evaluated exactly where the law defines it. The two fortnights add up to the month per line, which is what makes them reconcile against the monthly filing. period.days takes no part in the split — the factor comes from period.type. If days is not 15, the response carries a PERIOD_DAYS_IGNORED warning. weekly is rejected because a month does not contain a whole number of weeks, so four weeks cannot be made to add up to the monthly filing. See Pay periods for the full model and the cost of the naive shortcut.

Example request — biweekly

curl -X POST https://api.clevis.dev/v1/payroll/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "CO",
    "scheme": "ordinario",
    "year": 2026,
    "period": {
      "type": "biweekly",
      "start_date": "2026-09-01",
      "end_date": "2026-09-15",
      "days": 15
    },
    "employee": {
      "id": "emp_001",
      "daily_salary": 100000,
      "monthly_salary": 3000000,
      "risk_class_rate": 0.00522
    },
    "employer": { "id": "employer_001" }
  }'

The response reports period_basis.sequence: 1, periods_in_month: 2 and a monthly_equivalent you can reconcile the month against.

Ordinario

The ordinario scheme covers standard employees under Colombian labor law (Codigo Sustantivo del Trabajo). Includes all mandatory social security contributions and income tax withholding.

What it calculates

Employee deductions:

Salud — Health contribution (4% employee share)
Pension — Pension contribution (4% employee share)
Fondo de Solidaridad Pensional — Solidarity fund for salaries >= 4 SMMLV
Retencion en la fuente — Income tax withholding using UVT-based progressive brackets

Employer contributions:

Salud patronal — Employer health (8.5%)
Pension patronal — Employer pension (12%)
ARL — Occupational risk insurance
Parafiscales — SENA, ICBF, Caja de Compensacion

Employee inputs

Field	Type	Required	Default	Description
`monthly_salary`	number	Yes	—	Salario mensual
`daily_salary`	number	Yes	—	Salario diario (monthly / 30)
`risk_class_rate`	number	Yes	—	ARL rate for the employer’s risk class, as a fraction
`horas_recargo_nocturno`	number	No	`0`	Ordinary hours worked in the night band, weekday
`horas_dominicales_diurnas`	number	No	`0`	Ordinary hours on a Sunday or holiday, day band
`horas_dominicales_nocturnas`	number	No	`0`	Ordinary hours on a Sunday or holiday, night band
`horas_extra_diurnas`	number	No	`0`	Overtime hours, weekday, day band
`horas_extra_nocturnas`	number	No	`0`	Overtime hours, weekday, night band
`horas_extra_dominicales_diurnas`	number	No	`0`	Overtime hours on a Sunday or holiday, day band
`horas_extra_dominicales_nocturnas`	number	No	`0`	Overtime hours on a Sunday or holiday, night band
`overrides.aplica_auxilio_transporte`	boolean	No	false	Set `true` when the employee is entitled to Auxilio de transporte
`overrides.aplica_exoneracion_114_1`	boolean	No	false	Set `true` when the employer is exonerated under ET Art. 114-1

risk_class_rate has no default. A request for Colombia that omits it is rejected with 422 VALIDATION_ERROR on employee.risk_class_rate; in a batch, the path is employees.{i}.risk_class_rate and the whole batch is rejected before any row runs.

ARL risk classes (Decreto 1607/2002)

The class is assigned by the ARL, never by Clevis. This table is reference material: the engine receives the rate already resolved and never a class label, because mapping an economic activity (CIIU) to a risk class would require the activity catalogue of every country. Clevis does not validate that the rate matches the employer’s activity.

Class	Typical activity	Rate
Class I	Mostly administrative, professional and office-based activities	`0.00522`
Class II	Commercial activities, retail/wholesale, restaurants, hotels, and other relatively low-risk service activities	`0.01044`
Class III	Manufacturing, industrial processing, workshops, and activities involving moderate physical or operational risks	`0.02436`
Class IV	Armed security, transport	`0.04350`
Class V	Construction, mining	`0.06960`

Horas extra y recargos

The client classifies the hours; the engine does not. Clevis receives hours already sorted into the seven buckets above. Deciding whether an hour is nocturna, dominical or festiva needs a holiday calendar and a shift clock, both of which live in your system. There is no holiday calendar in this API.

Hours accept fractional values. The 0-400 validation bound is a guard against garbage input, not the legal cap — Clevis does not enforce CST Art. 167 (2 h/day, 12 h/week). The distinction that matters: for an ordinary hour worked at night or on a Sunday the 100% is already inside the monthly salary, so only the surcharge is settled. For an overtime hour the hour itself is not in the salary, so it is paid in full plus the surcharge.

Concept	Factor on the hourly rate	Composition
`recargo_nocturno`	0.35	surcharge only
`recargo_dominical`	0.90	surcharge only
`recargo_dominical_nocturno`	1.25	0.90 + 0.35
`hora_extra_diurna`	1.25	1.00 + 0.25
`hora_extra_nocturna`	1.75	1.00 + 0.75
`hora_extra_dominical_diurna`	2.15	1.00 + 0.90 + 0.25
`hora_extra_dominical_nocturna`	2.65	1.00 + 0.90 + 0.75

Surcharges add, they do not compound. A nocturnal Sunday overtime hour is 1 + 0.90 + 0.75, not 1 x 1.90 x 1.75. Horas extra and recargos are salary (CST Art. 127), so they feed the IBC and the prima and cesantias bases.

Ley 2466 de 2025 — rates resolve by date

The recargo dominical is modelled as a time series, not a constant. The rate is resolved from period.start_date, so a June 2026 period resolves 0.80 and a July 2026 period resolves 0.90.

In force from	Recargo dominical
Until Jun 2025	75%
1 Jul 2025	80%
1 Jul 2026	90%
1 Jul 2027	100%

The 2027 step is already loaded — a July 2027 period resolves the right rate with no change on your side. The night band also starts at 7:00 p.m. (previously 9:00 p.m.) from 25 Dec 2025, also under Ley 2466.

Exoneracion parafiscal (ET Art. 114-1)

overrides.aplica_exoneracion_114_1 exempts employer salud, SENA and ICBF. It does not cover CCF or pension. The flag is per employee, not per company: the same company exonerates a worker earning 3 SMMLV and pays in full for one earning 12. Clevis receives the flag already resolved, because the exoneration also requires the employer to be a corporate income tax filer — an attribute of the company that never arrives in a request.

Threshold warnings

Two flags are checked against the salary that gates them. A mismatch produces an entry in warnings and never changes an amount — the calculation honours the flag as sent.

Flag	Threshold	Basis
`aplica_auxilio_transporte`	`<= 2 SMMLV` (inclusive)	Ley 15/1959
`aplica_exoneracion_114_1`	`< 10 SMMLV` (exclusive)	ET Art. 114-1

Both are measured on salario_basico, not on total earnings. Each warning message states exactly what it compared, so a payroll officer who disagrees can see the criterion rather than guess it. aplica_exoneracion_114_1 only warns when it is on above the threshold, not when it is off. Warning on the off case would fire on almost every legitimate ordinary request, which is how an integrator learns to ignore the channel altogether.

Key reference values

Value	2025	2026
SMMLV	$1,423,500	$1,423,500
UVT	$49,799	$49,799
Auxilio de transporte	$200,000	$200,000

Example request

curl -X POST https://api.clevis.dev/v1/payroll/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "CO",
    "scheme": "ordinario",
    "year": 2025,
    "period": {
      "type": "monthly",
      "start_date": "2025-03-01",
      "end_date": "2025-03-31",
      "days": 30
    },
    "employee": {
      "id": "emp_001",
      "daily_salary": 100000,
      "monthly_salary": 3000000,
      "risk_class_rate": 0.00522
    },
    "employer": { "id": "employer_001" }
  }'

Response bases

Two bases in the response were separated, which is visible if you already parse it:

Base	What it covers
`base_vacaciones`	Excludes horas extra and work on mandatory rest days (CST Art. 192 num. 2), but includes recargo nocturno — that is part of the ordinary salary of the shift
`base_prestaciones_prima`	Formerly `base_prestaciones_ordinarias`

The employer table prestaciones_prima_vacaciones_patron was likewise split into prestaciones_prima_patron and prestaciones_vacaciones_patron. Both changes show up in the response and in the audit trail.

The integral scheme does not settle surcharges separately — the 30% prestational factor absorbs them. The seven hour fields apply to ordinario only.

Integral

The integral scheme applies to employees earning >= 13 SMMLV (salario integral). Social security contributions are calculated on 70% of the salary, and the remaining 30% is considered a prestational component.

What it calculates

Salud and pension — Calculated on 70% of salary (IBC)
Fondo de Solidaridad Pensional — Progressive rates based on salary in SMMLV
Retencion en la fuente — UVT-based progressive brackets (Procedimiento 1)

Key differences from ordinario

Aspect	Ordinario	Integral
Minimum salary	1 SMMLV	13 SMMLV
SS contribution base	100% salary	70% salary
Prestaciones sociales	Separate (prima, cesantias)	Included in salary

Example request

curl -X POST https://api.clevis.dev/v1/payroll/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "CO",
    "scheme": "integral",
    "year": 2025,
    "period": {
      "type": "monthly",
      "start_date": "2025-03-01",
      "end_date": "2025-03-31",
      "days": 30
    },
    "employee": {
      "id": "emp_001",
      "daily_salary": 700000,
      "monthly_salary": 21000000,
      "risk_class_rate": 0.00522
    },
    "employer": { "id": "employer_001" }
  }'

Get Started

Countries

Calculations

Payouts

Guides

Available schemes

Supported pay periods

Example request — biweekly

Ordinario

What it calculates

Employee inputs

ARL risk classes (Decreto 1607/2002)

Horas extra y recargos

Ley 2466 de 2025 — rates resolve by date

Exoneracion parafiscal (ET Art. 114-1)

Threshold warnings

Key reference values

Example request

Response bases

Integral

What it calculates

Key differences from ordinario

Example request

​Available schemes

​Supported pay periods

​Example request — biweekly

​Ordinario

​What it calculates

​Employee inputs

​ARL risk classes (Decreto 1607/2002)

​Horas extra y recargos

​Ley 2466 de 2025 — rates resolve by date

​Exoneracion parafiscal (ET Art. 114-1)

​Threshold warnings

​Key reference values

​Example request

​Response bases

​Integral

​What it calculates

​Key differences from ordinario

​Example request

Available schemes

Supported pay periods

Example request — biweekly

Ordinario

What it calculates

Employee inputs

ARL risk classes (Decreto 1607/2002)

Horas extra y recargos

Ley 2466 de 2025 — rates resolve by date

Exoneracion parafiscal (ET Art. 114-1)

Threshold warnings

Key reference values

Example request

Response bases

Integral

What it calculates

Key differences from ordinario

Example request