Skip to main content
POST
/
v1
/
tax
/
calculate
curl --request POST \
  --url https://api.cadanapay.com/v1/tax/calculate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "personId": "81933bed-97ba-4477-81a7-b8c5ab507b6f",
  "salary": {
    "amount": 4000000,
    "currency": "MXN"
  },
  "additionalAttributes": {
    "ytdSalary": 4000000
  }
}
'
{
  "personId": "81933bed-97ba-4477-81a7-b8c5ab507b6f",
  "grossAmount": {
    "amount": 1000000,
    "currency": "BRL"
  },
  "netAmount": {
    "amount": 761244,
    "currency": "BRL"
  },
  "deductions": [
    {
      "name": "INSS (Instituto Nacional do Seguro Social)",
      "isStatutory": true,
      "amount": {
        "amount": 82839,
        "currency": "BRL"
      }
    },
    {
      "name": "IRRF (Imposto de Renda Retido na Fonte)",
      "isStatutory": true,
      "amount": {
        "amount": 155917,
        "currency": "BRL"
      }
    }
  ],
  "employerContributions": [
    {
      "name": "FGTS (Fundo de Garantia do Tempo de Serviço)",
      "isStatutory": true,
      "amount": {
        "amount": 80000,
        "currency": "BRL"
      }
    }
  ],
  "summary": {
    "gross": {
      "name": "Gross Salary",
      "amount": 1000000,
      "calculation": {
        "description": "Monthly base salary calculation",
        "inputValues": {
          "baseSalary": 1000000
        },
        "formula": "baseSalary",
        "steps": [
          "Base salary amount: R$10000.00"
        ]
      }
    },
    "deductions": [
      {
        "name": "INSS (Instituto Nacional do Seguro Social)",
        "amount": 82839,
        "calculation": {
          "description": "Brazilian Social Security contribution based on 2024 INSS tables",
          "inputValues": {
            "grossSalary": 10000,
            "bracket1Rate": 0.075,
            "bracket2Rate": 0.09,
            "bracket3Rate": 0.12,
            "bracket4Rate": 0.14,
            "bracket1Limit": 1320,
            "bracket2Limit": 2571.29,
            "bracket3Limit": 3856.94,
            "bracket4Limit": 7507.49
          },
          "formula": "Progressive rate calculation based on salary brackets",
          "steps": [
            "Bracket 1: 1320.00 * 7.5% = 99.00",
            "Bracket 2: (2571.29 - 1320.00) * 9% = 112.62",
            "Bracket 3: (3856.94 - 2571.29) * 12% = 154.28",
            "Bracket 4: (7507.49 - 3856.94) * 14% = 462.49",
            "Total INSS contribution: R$828.39"
          ]
        }
      },
      {
        "name": "IRRF (Imposto de Renda Retido na Fonte)",
        "amount": 155917,
        "calculation": {
          "description": "Brazilian Income Tax calculation based on 2024 rates",
          "inputValues": {
            "grossSalary": 10000,
            "inssDeduction": 828.39,
            "baseCalculation": 9171.61,
            "dependentsDeduction": 0,
            "irrfRate": 0.275,
            "deduction": 869.36
          },
          "formula": "(baseCalculation * irrfRate) - deduction",
          "steps": [
            "Gross salary: R$10000.00",
            "INSS deduction: R$828.39",
            "Base for IRRF: R$9171.61",
            "Apply 27.5% rate: R$9171.61 * 0.275 = R$2522.19",
            "Deduction amount: R$869.36",
            "Final IRRF: R$1559.17"
          ]
        }
      }
    ],
    "net": {
      "name": "Net Salary",
      "amount": 761244,
      "calculation": {
        "description": "Final take-home pay calculation",
        "inputValues": {
          "grossSalary": 10000,
          "inssDeduction": 828.39,
          "irrfDeduction": 1559.17
        },
        "formula": "grossSalary - inssDeduction - irrfDeduction",
        "steps": [
          "Gross salary: R$10000.00",
          "INSS deduction: R$828.39",
          "IRRF deduction: R$1559.17",
          "Net salary: R$7612.44"
        ]
      }
    },
    "employerContributions": [
      {
        "name": "FGTS (Fundo de Garantia do Tempo de Serviço)",
        "amount": 80000,
        "calculation": {
          "description": "Employer's FGTS contribution calculation",
          "inputValues": {
            "grossSalary": 10000,
            "fgtsRate": 0.08
          },
          "formula": "grossSalary * fgtsRate",
          "steps": [
            "Calculate 8% FGTS: R$10000.00 * 8% = R$800.00"
          ]
        }
      }
    ]
  }
}
{
  "code": "invalid_request_body",
  "message": "The request body provided is not valid",
  "params": {
    "field": "Value is invalid."
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-MultiTenantKey
string

Required when using a Platform API token. The tenant key identifying which business to operate on.

Body

application/json
​
personId
string
required

ID of the Cadana person to calculate taxes for. The person's address determines the jurisdiction, and their stored compensation and tax profile provide calculation inputs.

​
salary
object
​
bonus
object

Bonus amount for the period, included in gross and taxable income.

​
overtime
object

Overtime amount for the period.

​
allowances
object[]

Allowance line items (e.g. housing, meal stipends). Each carries a name, isTaxable, and amount. Pass isTaxable explicitly — when omitted it defaults to false, meaning the allowance counts toward gross pay but not taxable income.

​
deductions
object[]

Voluntary (non-statutory) deduction line items to apply. Items with isStatutory: true are ignored — statutory items like income tax and social security are computed by the engine.

​
additionalAttributes
object

Country-specific calculation inputs (e.g. ytdSalary, riskCategory). Use GET /v1/tax/fields?country={code} to discover what each jurisdiction accepts. Numeric fields are expressed in major currency units — e.g. India's hraReceived, rentPaid, declared80c, and annualBaseSalary are whole rupees — unlike amount objects, which use the lowest denomination.

Response

Calculate taxes response

​
personId
string
required

ID of the person taxes were calculated for

​
grossAmount
object
required
​
netAmount
object
required
​
deductions
object[]
required
​
employerContributions
object[]
required
​
allowances
object[]

Imputed-income line items (e.g. benefits-in-kind) surfaced by the country engine. Omitted when none apply.

​
summary
object