Clean Paycheck Engine

The core salary orchestration engine. Calculate how gross income is allocated to obligation vaults, safety buffers, and safe-to-spend. Uses decimal.js precision with ROUND_HALF_UP for all monetary calculations.

/api/v1/engine/paycheck

Endpoints

POST

/api/v1/engine/paycheck/calculate

Calculate a clean paycheck from gross income and obligations

GET

/api/v1/engine/paycheck/{id}/breakdown

Get detailed breakdown of a previous calculation

GET

/api/v1/engine/paycheck/history

List calculation history for an employee

POST

/api/v1/engine/paycheck/simulate

Simulate a paycheck without persisting results

Parameters

Parameter	Type	Required	Description
employee_id	string	Required	Employee identifier
gross_pay	integer	Required	Gross pay amount in pence
obligations	array	Required	List of obligations with type, amount (pence), and category
include_history	boolean	Optional	Include previous calculation for comparison

Example

Request

http

POST /api/v1/engine/paycheck/calculate HTTP/1.1
Host: api.tpay365.com
Authorization: Bearer sk_live_abc123
Content-Type: application/json

{
  "employee_id": "emp_8821-9920",
  "gross_pay": 285000,
  "obligations": [
    { "type": "RENT", "amount": 95000, "category": "FIXED" },
    { "type": "ENERGY", "amount": 12500, "category": "FIXED" },
    { "type": "NETFLIX", "amount": 1599, "category": "SAVINGS" }
  ]
}

Response

json

{
  "id": "pc_xyz789",
  "gross_income": 285000,
  "locked_for_bills": 109099,
  "locked_buffer": 5450,
  "clean_safe_to_spend": 170451,
  "vaults": [
    { "type": "RENT", "amount": 95000, "category": "FIXED" },
    { "type": "ENERGY", "amount": 12500, "category": "FIXED" },
    { "type": "NETFLIX", "amount": 1599, "category": "SAVINGS" }
  ],
  "buffer_rate": "0.05",
  "calculated_at": "2026-02-10T14:30:00Z"
}