Swiftpack.co - hmrc/tax-kalculator as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by hmrc.
hmrc/tax-kalculator 2.7.1
Kotlin Multiplatform Project for calculating take-home pay 💰
⭐️ 12
🕓 2 days ago
.package(url: "https://github.com/hmrc/tax-kalculator.git", from: "2.7.1")


Build Status Github swift-pm


Calculate take home pay

Create an instance of Calculator, providing values as per the following example:


val calculator = Calculator(
    taxCode = "1257L",               // Required
    wages = 20000.0,                 // Required
    payPeriod = YEARLY,              // Required
    isPensionAge = false,            // Optional (Default: false)
    howManyAWeek = null,             // Optional (Default: null)
    taxYear = TaxYear.currentTaxYear // Optional (Default: Current Tax Year)

val response = calculator.run()


let calculator = Calculator(
    taxCode: "1257L",
    wages: 20000.0,
    payPeriod: period,
    isPensionAge: false,
    howManyAWeek: KotlinDouble(double: 35),
    taxYear: TaxYear.companion.currentTaxYear

let calculation = try calculator.run()

The default values are working in Android (and other JVM) but currently do not seem to be present in iOS, so pass in the default values for now.

Returns an object of type CalculatorResponse. This class is broken up into weekly, four_weekly, monthly and yearly. Each of these members is of type CalculatorResponsePayPeriod and the members of this class are what will return the values (relative to their PayPeriod) needed for the app, they are:

  • taxToPay of type Double (This will be capped at a maximum of 50% of their wages)
  • maxTaxAmountExceeded of type Boolean (This will always be false unless taxToPay is adjusted for 50%)
  • employeesNI of type Double
  • employersNI of type Double
  • wages of type Double
  • taxBreakdown of type List<BandBreakdown>
  • taxFree of type Double
  • totalDeductions of type Double
  • takeHome of type Double

For tax breakdown this is the amount of tax per tax band which has two members, percentage: Double and amount: Double.


Default Tax Code


val taxCode = CalculatorUtils.defaultTaxCode(taxYear = 2022)


let taxCode = CalculatorUtils.shared.defaultTaxCode(taxYear: 2022)

Current Tax Year


val year = CalculatorUtils.currentTaxYear()


let year = CalculatorUtils.shared.currentTaxYear()


Validate a tax code:


val isValid = TaxCodeValidator.isValidTaxCode(taxCode = "1257L") // TaxCodeValidationResponse(true)
val isValid = TaxCodeValidator.isValidTaxCode(taxCode = "OO9999") // TaxCodeValidationResponse(false, ValidationError.WrongTaxCodePrefix)
val isValid = TaxCodeValidator.isValidTaxCode(taxCode = "9999R") // TaxCodeValidationResponse(false, ValidationError.WrongTaxCodeSuffix)
val isValid = TaxCodeValidator.isValidTaxCode(taxCode = "HELLO") // TaxCodeValidationResponse(false, ValidationError.WrongTaxCodeNumber)
val isValid = TaxCodeValidator.isValidTaxCode(taxCode = "110") // TaxCodeValidationResponse(false, ValidationError.Other)


let isValid = TaxCodeValidator.shared.isValidTaxCode(taxCode: "1257L") // TaxCodeValidationResponse(true)
let isValid = TaxCodeValidator.shared.isValidTaxCode(taxCode: "OO9999") // TaxCodeValidationResponse(false, ValidationError.WrongTaxCodePrefix)
let isValid = TaxCodeValidator.shared.isValidTaxCode(taxCode: "9999R") // TaxCodeValidationResponse(false, ValidationError.WrongTaxCodeSuffix)
let isValid = TaxCodeValidator.shared.isValidTaxCode(taxCode: "HELLO") // TaxCodeValidationResponse(false, ValidationError.WrongTaxCodeNumber)
let isValid = TaxCodeValidator.shared.isValidTaxCode(taxCode: "110") // TaxCodeValidationResponse(false, ValidationError.Other)

Validate wages:


val isValidWages = WageValidator.isValidWages(wages = 1000) // true
val isAboveMinimumWages = WageValidator.isAboveMinimumWages(wages = 0.0) // false
val isBelowMaximumWages = WageValidator.isBelowMaximumWages(wages = 120000.0) // true


let isValidWages = WageValidator.shared.isValidWages(wages: 1000) // true
let isAboveMinimumWages = WageValidator.shared.isAboveMinimumWages(wages: 0.0) // false
let isBelowMaximumWages = WageValidator.shared.isBelowMaximumWages(wages: 120000.0) // true

Validate hours worked per week:


val isValidHoursPerWeek = HoursDaysValidator.isValidHoursPerWeek(hours = 20) // true
val isAboveMinimumHoursPerWeek = HoursDaysValidator.isAboveMinimumHoursPerWeek(hours = 1.0) // true
val isBelowMaximumHoursPerWeek = HoursDaysValidator.isBelowMaximumHoursPerWeek(hours = 170.0) // false
val isValidHoursPerDay = HoursDaysValidator.isValidHoursPerDay(hours = 20) // true
val isAboveMinimumHoursPerDay = HoursDaysValidator.isAboveMinimumHoursPerDay(hours = 1.0) // true
val isBelowMaximumHoursPerDay = HoursDaysValidator.isBelowMaximumHoursPerDay(hours = 25.0) // false


let isValidHoursPerWeek = HoursDaysValidator.shared.isValidHoursPerWeek(hours: 20) // true
let isAboveMinimumHoursPerWeek = HoursDaysValidator.shared.isAboveMinimumHoursPerWeek(hours: 1.0) // true
let isBelowMaximumHoursPerWeek = HoursDaysValidator.shared.isBelowMaximumHoursPerWeek(hours: 170.0) // false
let isValidHoursPerDay = HoursDaysValidator.shared.isValidHoursPerDay(hours: 20) // true
let isAboveMinimumHoursPerDay = HoursDaysValidator.shared.isAboveMinimumHoursPerDay(hours: 1.0) // true
let isBelowMaximumHoursPerDay = HoursDaysValidator.shared.isBelowMaximumHoursPerDay(hours: 25.0) // false


To run all tests and coverage verification:

./gradlew check



Swift Package Manager

Because this operates as a closed source, binary dependency, Swift PM will only work with tagged releases and not branches.


Simulator Architectures:

  • If the framework is downloaded and linked in the project, it'll be necessary to strip unwanted architectures in a build step.
    • For example, you may want to implement something like this.

Android & JVM

Add the Github Package repository to your top-level build.gradle, along with a Github username and access token (no permissions required).

repositories {
    maven {
        url = "https://maven.pkg.github.com/hmrc/tax-kalculator"
        credentials {
            username = System.getenv("GITHUB_USER_NAME")
            password = System.getenv("GITHUB_TOKEN")

Add the dependency in the build.gradle of the module:

dependencies {
    implementation "uk.gov.hmrc:tax-kalculator-jvm:x.y.z"

Release process

bundle exec fastlane tag_release


  • A valid Bitrise access token saved in your path under the variable name BITRISE_TOKEN. See Bitrise docs.
  • Two environment variables, TAX_KALC_APP_SLUG & TAX_KALC_RELEASE_WORKFLOW_ID will also need to be included in your bash/ZSH profile. Speak with Chris to obtain these values.

Steps executed

  • Ensure git status is clean
  • Ensure main branch
  • Through the interactive shell, select the tag version using semantic versioning.
  • Locally executes build_xcframework.sh:
    • Creates an XCFramework
    • Computes and updates the checksum in the Swift Package declaration.
  • Stamps the changelog
  • Commit and push the updated Package.swift and CHANGELOG.md
  • Upload release artifacts to tagged Github release
  • Executes release.sh to start the CI pipeline on CI.

How to update rates for new tax years

Tax Bands

Each tax band is represented with the following data structure:

internal data class TaxBand(
    override var lower: Double, // lower threshold of band
    override var upper: Double, // upper threshold of band
    override val percentageAsDecimal: Double // tax rate of band
) : Band

In TaxBands.kt update bands as specified by the business.

Usually England and Wales have the same bands. Whereas Scotland's are different.

// England and Wales
private fun restOfUK2022Bands() = listOf(
    TaxBand(0.0, 37700.00, 0.2),
    TaxBand(37700.00, 150000.00, 0.4),
    TaxBand(150000.0, -1.0, 0.45)

// Scotland
private fun scottish2022Bands() = listOf(
    TaxBand(0.00, 2162.00, 0.19),
    TaxBand(2162.00, 13118.00, 0.20),
    TaxBand(13118.00, 31092.00, 0.21),
    TaxBand(31092.00, 150000.00, 0.41),
    TaxBand(150000.00, -1.0, 0.46)

National Insurance Bands

Employee and Employer bands are represented with the following data structures:

internal data class EmployeeNIBand(
    override var lower: Double, // lower threshold of band
    override var upper: Double, // upper threshold of band
    override val percentageAsDecimal: Double // tax rate of band
) : Band

internal data class EmployerNIBand(
    override var lower: Double, // lower threshold of band
    override var upper: Double, // upper threshold of band
    override val percentageAsDecimal: Double // tax rate of band
) : Band

In EmployeeNIBands.kt and EmployerNIBands.kt update bands as specified by the business.

private val employeeNIBands2022: List<EmployeeNIBand> = listOf(
    EmployeeNIBand(9880.0, 50270.00, 0.1325),
    EmployeeNIBand(50270.0, -1.0, 0.0325)

private val employerNIBands2022: List<EmployerNIBand> = listOf(
    EmployerNIBand(9100.0, 50270.00, 0.1505),
    EmployerNIBand(50270.0, -1.0, 0.1505)


This code is open source software licensed under the Apache 2.0 License.


Stars: 12
Last commit: 2 days ago
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Release Notes

2 days ago
  • Fixed issue with the .jar name for JVM consumers.

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics