Skip to main content

​
1. Get your API key

Contact melvin@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
    },
    "employer": {
      "id": "employer_001"
    }
  }'

​
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"
    }
  ]
}
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 }
  }'
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

Learn about API key authentication and rate limits.

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.