# Tax cards

Salaxy withholds tax from each salary using the employee's **tax card** (*verokortti*). In nearly every case you let Salaxy fetch the card automatically; you set one by hand only when you must.

Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Two sources feed the tax card that Salaxy keeps for an employee: the automatic card, which Salaxy fetches from the Tax Administration, and a manual card that you set through the REST API. The salary calculation uses the card to work out the withholding tax. (Purple: Salaxy. The automatic card needs nothing from you except <code>info.taxcard: "auto"</code>.)*

## Which fits you?

### Automatic card

Fits almost everyone: Salaxy fetches the card from the Tax Administration, and refreshes it.

**Automatic card: how it works:**
Set `info.taxcard` to `auto` on the [employment](https://code.salaxy.com/integration/employments.md). Salaxy asks the Tax Administration for the card. You send nothing else.

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v03/api/taxcards/auto-set` | Fetch and set the automatic card now. Query: `personalId`, `taxPercentMinimum`, `salaryDate` (default: today) |
| `POST` | `/v03/api/taxcards/auto-refresh` | Check cards again. Query: `taxcardIds`, `salaryDate`, `forceUpdate` |
| `GET` | `/v03/api/taxcards/current` | The current cards of all non-terminated employments of the employer |
| `GET` | `/v03/api/taxcards/current/{paymentDate}` | The same for a payment date |
| `GET` | `/v03/api/taxcards/employment/{id}` | All current cards of one employment. Query: `paymentDate` |

- **The income type is always salary** for an automatic card at the moment.
- **A refresh is skipped if the card was checked within 2 days.** `forceUpdate=true` skips that rule. If nothing changed, only the last-checked date is updated; if something changed, a new card is created.
- **Around the turn of the year,** the current card may be the one for next year: in December and January `current` can return next year's card.
- The worker can set a **minimum percentage** (`taxPercentMinimum`) that is withheld even when the card's percentage is lower.

### Manual card

Fits when you hold the card yourself, for example a paper or PDF card, or a percentage the employer has agreed.

**Manual card: how it works:**
Set `info.taxcard` to `manual` on the employment, then save a tax card for it.

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v03/api/taxcards/new` | A blank card to fill in |
| `POST` | `/v03/api/taxcards` | Create or update a card |
| `GET` | `/v03/api/taxcards/{id}` | Read one card |
| `DELETE` | `/v03/api/taxcards/{id}` | Delete a card |
| `GET` | `/v03/api/taxcards` | Find cards. OData query; see [Queries](https://code.salaxy.com/reference/queries.md) |

```http
POST /v03/api/taxcards HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "employmentId": "EMP123",
  "card": {
    "personalId": "190372-942M",
    "forYear": 2026,
    "kind": "defaultYearly",
    "taxPercent": 10,
    "incomeLimit": 10000,
    "taxPercent2": 40,
    "validity": { "start": "2026-01-01", "end": "2026-12-31" }
  }
}
```

| Field | Meaning |
|---|---|
| `employmentId` | The employment the card is for |
| `card.personalId` | The Personal ID as written on the card |
| `card.forYear` | The year the card is valid for. Typically from February of that year to January of the next |
| `card.taxPercent` | The percentage as a percentage: 50 means 50 %, not 0.5 |
| `card.incomeLimit` | The income up to which `taxPercent` applies |
| `card.taxPercent2` | The percentage for the part of the income above the limit |
| `card.kind` | `defaultYearly`, `replacement`, `noWithholdingHousehold`, `others`, `historical`, `noTaxCard` or `auto` |
| `card.validity` | The validity dates as expressed on the card |

Saving a card for an employment that already has paid calculations can check them and add the difference to the card's income log.

The card is a separate `Taxcard` object, not a field of the employment or the calculation. When a calculation is recalculated, Salaxy picks the card valid for its payment date by the worker's Personal ID and copies it into the calculation.

## Other endpoints

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v03/api/taxcards/calculate` | Calculate the withholding tax for a given card. Query: `income`, `paymentDate` (decides the tax year) |
| `POST` | `/v03/api/taxcards/reload-calcs/{id}` | Rebuild the income log from the paid calculations. Does not save |
| `GET` | `/v03/api/taxcards/shared-exists/{personalId}` | Before the employment exists: is there a card the worker has shared? |
| `POST` | `/v03/api/taxcards/approve/{method}` | Approve or reject a worker-shared card. `method` is `assureWaiting`, `approve` or `reject`. Query: `ownedId` or `sharedUri` |

A card carries a `state`: `new`, `approved`, `employerAdded`, `verifiedVero`, `sharedWaiting`, `sharedApproved`, `sharedRejected`, `sharedRejectedWithoutOpen` or `shared`.

## Rules to know

- **An employment left at status `unknown` is treated as active** by the yearly tax card update. End employments properly: see [Employees and employments](https://code.salaxy.com/integration/employments.md#end-an-employment).
- **A manual card is yours to keep current.** Check `forYear` and `validity` against the salary dates you pay.

## Test it

In the test environment, set `info.taxcard` to `auto` and read the card with `GET /v03/api/taxcards/employment/{id}`. To control what the Tax Administration answers for a test Personal ID, use the test-data tax card endpoint: see [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md). For a manual card, post the sample above for your test employment and check the result with `POST /v03/api/taxcards/calculate`.

## Checklist

- `info.taxcard` is `auto` unless you have a reason to hold the card yourself.
- For a manual card, `info.taxcard` is `manual` and the card has a `forYear` and validity matching the salary dates.
- You post percentages as percentages (10, not 0.1).
- Ended employments are set to `archived`, so the yearly update treats them as ended.

**Next:** [Dimensions (cost centres)](https://code.salaxy.com/integration/dimensions.md)
