Prerequisites
Active business on Cadana
Your business must be created and verified on the platform.
Check Location Support
Verify which countries and regions are supported. The response includes valid state/region codes needed when registering a payee.
curl -X GET 'https://api.cadanapay.com/v1/tax/locations' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"countries": [
{
"name": "Australia",
"code": "AU",
"regions": [
{ "name": "New South Wales", "code": "NSW" },
{ "name": "Victoria", "code": "VIC" },
{ "name": "Queensland", "code": "QLD" }
]
}
]
}
Get Required Tax Fields
Some countries require additional fields (marital status, number of dependents, etc.) for accurate calculations. Retrieve the required fields before registering a payee.
curl -X GET 'https://api.cadanapay.com/v1/tax/fields' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"country": "BD",
"fields": [
{
"name": "maritalStatus",
"required": true,
"type": "string",
"enum": ["single", "married", "divorced", "widowed"],
"description": "Marital status for tax deduction eligibility"
},
{
"name": "numberOfDependents",
"required": false,
"type": "number",
"description": "Number of dependents for tax relief"
}
]
}
Register a Tax Payee
Create a payee with their address, salary, and tax profile. The returned id is used for all subsequent tax calculations.
curl -X POST 'https://api.cadanapay.com/v1/tax/payee' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"id": "123e4567-e89b-12d3-a456-426614174000"
}
Manage Payees
Calculate Taxes
Calculate taxes for a registered payee. Pass the payeeId and the salary for the period.
curl -X POST 'https://api.cadanapay.com/v1/tax/calculate' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"payeeId": "123e4567-e89b-12d3-a456-426614174000",
"grossAmount": { "amount": 1000000, "currency": "BRL" },
"netAmount": { "amount": 761244, "currency": "BRL" },
"deductions": [
{
"name": "INSS (Instituto Nacional do Seguro Social)",
"amount": { "amount": 82839, "currency": "BRL" }
},
{
"name": "IRRF (Imposto de Renda Retido na Fonte)",
"amount": { "amount": 155917, "currency": "BRL" }
}
],
"employerContributions": [
{
"name": "FGTS (Fundo de Garantia do Tempo de Serviço)",
"amount": { "amount": 80000, "currency": "BRL" }
}
]
}
Response fields
| Field | Description |
|---|
grossAmount | Input salary for the period |
netAmount | Take-home pay after all deductions |
deductions | Employee deductions (social security, income tax, etc.) |
employerContributions | Employer-side costs not deducted from the employee’s pay |
summary | Step-by-step calculation breakdown showing formulas, brackets, and rates for each line item |
additionalAttributes field accepts country-specific values like year-to-date salary or pension contributions. These are calculation-time inputs — different from the tax profile fields set during payee registration. Use the tax fields endpoint to discover what’s available for each country.
Estimate Gross or Net Salary
For compensation planning, estimate taxes without registering a payee. Supports both gross-to-net and net-to-gross calculations.
Gross to net
curl -X POST 'https://api.cadanapay.com/v1/tax/estimate' \
-H 'Authorization: Bearer YOUR_API_KEY'
Net to gross
curl -X POST 'https://api.cadanapay.com/v1/tax/estimate' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"grossAmount": { "amount": 1000000, "currency": "QAR" },
"netAmount": { "amount": 930000, "currency": "QAR" },
"deductions": [
{ "name": "Social Insurance", "amount": { "amount": 70000, "currency": "QAR" } }
],
"employerContributions": [
{ "name": "Social Insurance", "amount": { "amount": 140000, "currency": "QAR" } }
]
}
Use the estimate endpoint to model compensation packages for potential hires before committing to a payee registration.
Next Steps
