> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clevis.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Calculate your first payroll in 5 minutes
## 1. Get your API key
Contact [melvin@clevis.dev](mailto: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.
```bash cURL theme={null}
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"
}
}'
```
```python Python theme={null}
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,
},
"employer": {
"id": "employer_001",
},
},
)
result = response.json()
print(result["summary"]["net_salary"])
```
```javascript Node.js theme={null}
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,
},
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.
```json theme={null}
{
"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](/payouts/quickstart). To test during development, set `processing.step_seconds: 0`
to run the mock state machine synchronously so the response already has
`status: "PAID"`.
```bash cURL theme={null}
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 }
}'
```
```python Python theme={null}
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"
```
```javascript Node.js theme={null}
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](/payouts/overview) for the full story.
## 5. Discover available schemes
List all schemes available for a country:
```bash theme={null}
curl https://api.clevis.dev/v1/payroll/schemes/MX \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Next steps
Learn about API key authentication and rate limits.
Explore Mexican payroll schemes, concepts, and inputs.
Process up to 500 employees in a single request.
Compare salary scenarios without persisting results.