Quickstart

1. Get your API key

Mail contact@clevis.dev to get your API key.

2. Calculate a payroll

Send a POST request with the employee’s salary, the country scheme, and the pay period.

curl -X POST https://api.clevis.dev/v1/payroll/calculate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "MX",
    "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": 800.00,
      "risk_class_rate": 0.00544
    },
    "employer": {
      "id": "employer_001"
    }
  }'

import httpx

response = httpx.post(
    "https://api.clevis.dev/v1/payroll/calculate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "country": "MX",
        "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": 800.00,
            "risk_class_rate": 0.00544,
        },
        "employer": {
            "id": "employer_001",
        },
    },
)

result = response.json()
print(result["summary"]["net_salary"])

const response = await fetch("https://api.clevis.dev/v1/payroll/calculate", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    country: "MX",
    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: 800.0,
      risk_class_rate: 0.00544,
    },
    employer: {
      id: "employer_001",
    },
  }),
});

const result = await response.json();
console.log(result.summary.net_salary);

3. Read the response

The response includes a summary, itemized perceptions and deductions, employer contributions, and an audit trail.

{
  "id": "01HX9B2KM3V4W5X6Y7Z8A9B0CD",
  "status": "success",
  "country": "MX",
  "scheme": "ordinario",
  "year": 2025,
  "summary": {
    "gross_salary": "24000.00",
    "total_perceptions": "24000.00",
    "total_deductions": "3960.75",
    "net_salary": "20039.25",
    "employer_contributions_total": "5832.48",
    "employer_total_cost": "29832.48"
  },
  "perceptions": [
    { "id": "sueldo", "label": "Sueldo mensual", "amount": "24000.00", "taxable": true, "imss_base": true }
  ],
  "deductions": [
    { "id": "isr", "label": "ISR (Impuesto Sobre la Renta)", "amount": "2897.32" },
    { "id": "imss_empleado", "label": "IMSS Cuota obrera", "amount": "1063.43" }
  ],
  "audit_trail": [
    {
      "step": 1,
      "concept_id": "sueldo",
      "formula": "input.daily_salary * input.period_days",
      "inputs": { "input.daily_salary": "800.00", "input.period_days": "30" },
      "result_final": "24000.00"
    }
  ],
  "warnings": [],
  "period_basis": {
    "type": "monthly",
    "sequence": 1,
    "periods_in_month": 1,
    "factor": "1",
    "proration": "native",
    "absorbs_residual": true,
    "monthly_equivalent": {
      "total_perceptions": "24000.00",
      "total_deductions": "3960.75",
      "net_salary": "20039.25",
      "employer_contributions_total": "5832.48",
      "employer_total_cost": "29832.48"
    }
  },
  "record": {
    "stored": true,
    "rule_fingerprint": "sha256:b90834cebdc4224c3...",
    "engine_version": "9f2c1ab",
    "schema_version": 1,
    "content_digest": "sha256:41d0ae9f77b2c518...",
    "batch_id": null,
    "supersedes_id": null,
    "metadata": {}
  }
}

Four fields are worth pointing out, because they are always present:

id is a ULID. It is the key you use to fetch this calculation later, and it sorts by time.
warnings is always an array, never null — empty when there is nothing to flag. A warning never changes an amount. See Warnings.
period_basis is emitted even on monthly calculations, so you never branch on periodicity. See Pay periods.
record says what produced the number: which rule file, which engine build. See Provenance.

All monetary values are strings to prevent floating-point precision loss. Parse them with your language’s Decimal type before doing arithmetic.

4. Pay the net salary

Take the net_salary from the previous step and pay it out to the employee via the Payouts API. To test during development, set processing.step_seconds: 0 to run the mock state machine synchronously so the response already has status: "PAID".

curl -X POST https://api.clevis.dev/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: payroll-mx-2025-03-emp_001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "20039.25",
    "currency": "MXN",
    "country": "MX",
    "external_id": "payroll-mx-2025-03-emp_001",
    "beneficiary": {
      "name": "Juan García",
      "document_type": "RFC",
      "document_id": "GARJ800101ABC",
      "bank_account": { "clabe": "012180001234567890" }
    },
    "processing": { "step_seconds": 0 }
  }'

payout = httpx.post(
    "https://api.clevis.dev/v1/payouts",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "payroll-mx-2025-03-emp_001",
    },
    json={
        "amount": result["summary"]["net_salary"],  # string, straight through
        "currency": "MXN",
        "country": "MX",
        "external_id": "payroll-mx-2025-03-emp_001",
        "beneficiary": {
            "name": "Juan García",
            "document_type": "RFC",
            "document_id": "GARJ800101ABC",
            "bank_account": {"clabe": "012180001234567890"},
        },
        "processing": {"step_seconds": 0},
    },
).json()

assert payout["status"] == "PAID"

const payout = await fetch("https://api.clevis.dev/v1/payouts", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Idempotency-Key": "payroll-mx-2025-03-emp_001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: result.summary.net_salary,
    currency: "MXN",
    country: "MX",
    external_id: "payroll-mx-2025-03-emp_001",
    beneficiary: {
      name: "Juan García",
      document_type: "RFC",
      document_id: "GARJ800101ABC",
      bank_account: { clabe: "012180001234567890" },
    },
    processing: { step_seconds: 0 },
  }),
}).then((r) => r.json());

console.log(payout.status); // "PAID"

In sandbox enviroment payouts are handled by an in-process mock provider — no real funds are moved. Every response carries mock: true and the X-Clevis-Mock: true header. See the Payouts overview for the full story.

5. Discover available schemes

List all schemes available for a country:

curl https://api.clevis.dev/v1/payroll/schemes/MX \
  -H "Authorization: Bearer YOUR_API_KEY"

Next steps

Authentication

Key format, environments, and rotation without downtime.

Mexico

Explore Mexican payroll schemes, concepts, and inputs.

Batch calculate

Process up to 500 employees in a single request.

Simulate scenarios

Compare salary scenarios without persisting results.

Fortnightly payroll

Settle a fortnight in all six countries.

Stored calculations

Fetch a past payroll exactly as it was answered.

Get Started

Countries

Calculations

Payouts

Guides

1. Get your API key

2. Calculate a payroll

3. Read the response

4. Pay the net salary

5. Discover available schemes

Next steps

Authentication

Mexico

Batch calculate

Simulate scenarios

Fortnightly payroll

Stored calculations

​1. Get your API key

​2. Calculate a payroll

​3. Read the response

​4. Pay the net salary

​5. Discover available schemes

​Next steps

Authentication

Mexico

Batch calculate

Simulate scenarios

Fortnightly payroll

Stored calculations

1. Get your API key

2. Calculate a payroll

3. Read the response

4. Pay the net salary

5. Discover available schemes

Next steps