Calculate Taxes

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."
  }
}

POST

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.

version

string

Pin the calculation to a specific tax ruleset version, for example v2.1.0. Omit to use the current ruleset. An unknown, malformed or non-pinnable version is rejected with a 400 rather than silently falling back.

Example:

"v2.1.0"

salary

object

Show child attributes

bonus

object

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

Show child attributes

overtime

object

Overtime amount for the period.

Show child attributes

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.

Show child attributes

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.

Show child attributes

payPeriod

object

The dates the salary covers. If omitted, this defaults to a full calendar month.

Show child attributes

payPeriodFrequency

enum<string>

default:monthly

The pay period frequency. If omitted, this defaults to monthly.

Available options:

monthly,

semi-monthly,

bi-weekly,

weekly,

daily

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

Show child attributes

netAmount

object

required

Show child attributes

deductions

object[]

required

Show child attributes

employerContributions

object[]

required

Show child attributes

rulesetVersion

string

The pinned ruleset version this result was computed against. Returned only when the request pinned a version.

Example:

"v2.1.0"

allowances

object[]

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

Show child attributes

summary

object

Show child attributes

Overview

Payments API

Wallets API

Workforce API

Tax API

Statutory Compliance API

Authorizations

Headers

Body

Response