openapi: 3.0.0
info:
description: APIs for interacting with Cadana Embedded Consumer Wallets
version: 1.0.0
title: Embedded Consumer Wallets Balances Tax Calculator API
termsOfService: https://cadanapay.com/terms-and-conditions
contact:
email: api@cadanapay.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.cadanapay.com
description: Prod Server
- url: https://dev-api.cadanapay.com
description: Dev Server
security:
- Authorization: []
tags:
- name: Tax Calculator
description: APIs for tax calculations
paths:
/v1/tax/calculate:
post:
summary: Calculate Taxes
description: 'Calculate taxes for an existing Cadana person. The person''s address determines the jurisdiction, and their stored compensation and tax profile provide calculation inputs (overridden by `salary` when supplied).
Beyond the base salary, the request accepts the same per-entry earnings as a payroll entry — `allowances`, `bonus`, `overtime`, and voluntary `deductions` — and computes them identically to a payroll run.
'
operationId: calculateTaxesForPerson
tags:
- Tax Calculator
security:
- Authorization: []
parameters:
- $ref: '#/components/parameters/XMultiTenantKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CalculateTaxesRequest'
examples:
existingPerson:
summary: Calculate for existing person
value:
personId: 81933bed-97ba-4477-81a7-b8c5ab507b6f
salary:
amount: 4000000
currency: MXN
additionalAttributes:
ytdSalary: 4000000
withEarnings:
summary: Salary plus allowances and a bonus
value:
personId: 81933bed-97ba-4477-81a7-b8c5ab507b6f
salary:
amount: 4000000
currency: MXN
bonus:
amount: 500000
currency: MXN
allowances:
- name: Meal Allowance
isTaxable: true
amount:
amount: 200000
currency: MXN
responses:
'200':
$ref: '#/components/responses/CalculateTaxesResponse'
'400':
$ref: '#/components/responses/BadRequestError'
/v1/tax/fields:
get:
summary: List Required Additional Tax Fields by Country
description: Returns a list of tax-related additionalfields required to run calculations in the specified country
operationId: listCountryTaxFields
tags:
- Tax Calculator
security:
- Authorization: []
parameters:
- name: country
in: query
required: true
schema:
type: string
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
description: Required tax fields by country
content:
application/json:
schema:
$ref: '#/components/schemas/RequiredTaxFieldsResponse'
example:
data:
- 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
default: 0
- name: isResident
required: false
type: boolean
description: Whether the worker is a tax resident
default: true
- name: employerIndustry
required: false
type: string
description: Industry classification used for local tax variations
'400':
$ref: '#/components/responses/BadRequestError'
/v1/tax/locations:
get:
summary: List Countries and Regions
description: Returns a list of supported countries and their valid states/regions
operationId: listSupportedLocations
tags:
- Tax Calculator
security:
- Authorization: []
parameters:
- name: country
in: query
required: false
schema:
type: string
description: Optional country code to filter for a specific country and its regions
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
description: Supported countries and regions
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Country'
example:
data:
- name: Australia
code: AU
regions:
- name: New South Wales
code: NSW
- name: Victoria
code: VIC
- name: Queensland
code: QLD
'400':
$ref: '#/components/responses/BadRequestError'
/v1/tax/estimate:
post:
summary: Estimate Gross or Net Salary
description: Estimate gross or net salary for a given country and type
operationId: estimateTaxes
tags:
- Tax Calculator
security:
- Authorization: []
parameters:
- $ref: '#/components/parameters/XMultiTenantKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EstimateTaxesRequest'
examples:
grossToNet:
summary: Gross to Net estimation
value:
countryCode: PH
type: gross-to-net
salary:
amount: 5000000
currency: PHP
netToGross:
summary: Net to Gross estimation
value:
countryCode: MX
type: net-to-gross
net:
amount: 2000000
currency: MXN
responses:
'200':
$ref: '#/components/responses/EstimateTaxesResponse'
'400':
$ref: '#/components/responses/BadRequestError'
components:
schemas:
State:
type: object
properties:
name:
type: string
example: Dhaka
code:
type: string
example: DHA
Allowance:
type: object
required:
- name
- isTaxable
- amount
properties:
name:
type: string
isTaxable:
type: boolean
description: Whether the allowance is part of taxable income.
amount:
$ref: '#/components/schemas/Amount'
CalculationDetails:
type: object
properties:
description:
type: string
inputValues:
type: object
additionalProperties:
type: number
formula:
type: string
steps:
type: array
items:
type: string
EstimateTaxesResponse:
type: object
required:
- grossAmount
- netAmount
- deductions
- employerContributions
properties:
grossAmount:
$ref: '#/components/schemas/Amount'
netAmount:
$ref: '#/components/schemas/Amount'
allowances:
type: array
description: Imputed-income line items (e.g. benefits-in-kind) surfaced by the country engine. Omitted when none apply.
items:
$ref: '#/components/schemas/Allowance'
deductions:
type: array
items:
$ref: '#/components/schemas/Deduction'
employerContributions:
type: array
items:
$ref: '#/components/schemas/Deduction'
outputCurrency:
type: string
description: Echo of the requested `outputCurrency`. Present only when the request specified a conversion.
example: USD
fxRate:
type: string
description: FX rate applied to convert from the input currency to `outputCurrency`. Present only when a conversion was performed.
example: '0.058'
RequiredTaxFieldsResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
name:
type: string
description: Field key used in `additionalAttributes` on `POST /v1/tax/calculate` or in the person's `taxProfile`.
description:
type: string
type:
type: string
description: Data type of the field value (e.g. "string", "number", "boolean").
required:
type: boolean
enum:
type: array
items:
type: string
description: Allowed values when the field accepts a fixed set of options.
default:
description: Default value applied by the engine when the field is omitted from the calculation. Present only when the field declares a default. Use it to pre-fill onboarding forms — optional fields that have a default need no user input. The type matches the field's `type` (string, number, or boolean).
provider:
type: string
description: Internal source that surfaces this field. May be omitted.
BadRequestError:
description: Bad input provided by client
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
params:
description: A map for meta data around the error that occurred
type: object
example:
code: invalid_request_body
message: The request body provided is not valid
params:
field: Value is invalid.
Deduction:
type: object
required:
- name
- isStatutory
- amount
properties:
name:
type: string
isStatutory:
type: boolean
description: Whether the deduction is mandated by law (statutory) versus an optional voluntary deduction.
amount:
$ref: '#/components/schemas/Amount'
CalculateTaxesResponse:
type: object
required:
- personId
- grossAmount
- netAmount
- deductions
- employerContributions
properties:
personId:
type: string
description: ID of the person taxes were calculated for
grossAmount:
$ref: '#/components/schemas/Amount'
netAmount:
$ref: '#/components/schemas/Amount'
allowances:
type: array
description: Imputed-income line items (e.g. benefits-in-kind) surfaced by the country engine. Omitted when none apply.
items:
$ref: '#/components/schemas/Allowance'
deductions:
type: array
items:
$ref: '#/components/schemas/Deduction'
employerContributions:
type: array
items:
$ref: '#/components/schemas/Deduction'
summary:
$ref: '#/components/schemas/CalculateTaxesSummary'
CalculateTaxesRequest:
type: object
required:
- personId
properties:
personId:
type: string
description: 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:
$ref: '#/components/schemas/Amount'
bonus:
allOf:
- $ref: '#/components/schemas/Amount'
description: Bonus amount for the period, included in gross and taxable income.
overtime:
allOf:
- $ref: '#/components/schemas/Amount'
description: Overtime amount for the period.
allowances:
type: array
description: 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.
items:
type: object
required:
- name
- amount
properties:
name:
type: string
example: Meal Allowance
isTaxable:
type: boolean
default: false
description: Whether this allowance is included in taxable income. Defaults to `false` when omitted.
amount:
$ref: '#/components/schemas/Amount'
deductions:
type: array
description: '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.'
items:
type: object
required:
- name
- amount
properties:
name:
type: string
example: Gym Membership
isStatutory:
type: boolean
default: false
amount:
$ref: '#/components/schemas/Amount'
additionalAttributes:
type: object
description: 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.
Country:
type: object
properties:
name:
type: string
example: Bangladesh
code:
type: string
example: BD
regions:
type: array
items:
$ref: '#/components/schemas/State'
CalculateTaxesLineItem:
type: object
required:
- name
- amount
- calculation
properties:
name:
type: string
amount:
type: number
calculation:
$ref: '#/components/schemas/CalculationDetails'
Amount:
type: object
required:
- amount
- currency
properties:
amount:
type: number
description: value in lowest denomination
example: 10000
currency:
type: string
description: currency
example: BRL
EstimateTaxesRequest:
oneOf:
- required:
- countryCode
- type
- salary
type: object
properties:
countryCode:
type: string
description: Country code for tax estimation
regionCode:
type: string
description: Optional region/state code
type:
type: string
enum:
- gross-to-net
- net-to-gross
description: Type of estimation
salary:
$ref: '#/components/schemas/Amount'
outputCurrency:
type: string
description: ISO 4217 currency to convert response amounts into. When different from the salary currency, all amounts are converted at the prevailing FX rate and `fxRate` is populated on the response.
example: USD
- required:
- countryCode
- type
- net
type: object
properties:
countryCode:
type: string
description: Country code for tax estimation
regionCode:
type: string
description: Optional region/state code
type:
type: string
enum:
- gross-to-net
- net-to-gross
description: Type of estimation
net:
$ref: '#/components/schemas/Amount'
outputCurrency:
type: string
description: ISO 4217 currency to convert response amounts into. When different from the net currency, all amounts are converted at the prevailing FX rate and `fxRate` is populated on the response.
example: USD
CalculateTaxesSummary:
type: object
properties:
gross:
$ref: '#/components/schemas/CalculateTaxesLineItem'
deductions:
type: array
items:
$ref: '#/components/schemas/CalculateTaxesLineItem'
net:
$ref: '#/components/schemas/CalculateTaxesLineItem'
employerContributions:
type: array
items:
$ref: '#/components/schemas/CalculateTaxesLineItem'
Error:
type: object
properties:
code:
description: A machine parsable error code
type: string
enum:
- invalid_request_body
- resource_not_found
- forbidden
- internal_error
message:
description: A human readable message describing the error
type: string
parameters:
XMultiTenantKey:
name: X-MultiTenantKey
in: header
required: false
schema:
type: string
description: Required when using a Platform API token. The tenant key identifying which business to operate on.
responses:
EstimateTaxesResponse:
description: Estimate taxes response
content:
application/json:
schema:
$ref: '#/components/schemas/EstimateTaxesResponse'
examples:
grossToNet:
summary: Gross to Net estimation response (Philippines)
value:
grossAmount:
amount: 5000000
currency: PHP
netAmount:
amount: 4223167
currency: PHP
deductions:
- name: Social Security
isStatutory: true
amount:
amount: 175000
currency: PHP
- name: National Health Insurance (PhilHealth)
isStatutory: true
amount:
amount: 125000
currency: PHP
- name: Home Development Mutual Fund (PAG-IBIG)
isStatutory: true
amount:
amount: 20000
currency: PHP
- name: PAYE (Income Tax)
isStatutory: true
amount:
amount: 456833
currency: PHP
employerContributions:
- name: Social Security
isStatutory: true
amount:
amount: 350000
currency: PHP
- name: National Health Insurance (PhilHealth)
isStatutory: true
amount:
amount: 125000
currency: PHP
- name: Home Development Mutual Fund (PAG-IBIG)
isStatutory: true
amount:
amount: 20000
currency: PHP
- name: Employees' Compensation (EC)
isStatutory: true
amount:
amount: 3000
currency: PHP
netToGross:
summary: Net to Gross estimation response (Mexico)
value:
grossAmount:
amount: 2386014
currency: MXN
netAmount:
amount: 2000000
currency: MXN
deductions:
- name: Sickness and Maternity Insurance
isStatutory: true
amount:
amount: 21383
currency: MXN
- name: Disability and Life Insurance
isStatutory: true
amount:
amount: 15647
currency: MXN
- name: Severance at Advanced Age and Old Age
isStatutory: true
amount:
amount: 28166
currency: MXN
- name: Income Tax (ISR)
isStatutory: true
amount:
amount: 320818
currency: MXN
employerContributions:
- name: Work Risk Insurance
isStatutory: true
amount:
amount: 13609
currency: MXN
BadRequestError:
description: Bad input provided by client
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
CalculateTaxesResponse:
description: Calculate taxes response
content:
application/json:
schema:
$ref: '#/components/schemas/CalculateTaxesResponse'
examples:
brazilianTaxCalculation:
$ref: '#/components/examples/TaxCalculationExample'
examples:
TaxCalculationExample:
summary: Example Brazilian tax calculation response
value:
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'
securitySchemes:
Authorization:
type: http
scheme: bearer
bearerFormat: API_SECRET_KEY
x-readme:
explorer-enabled: true
proxy-enabled: true
samples-enabled: true