Skip to content
Since98
Documentation · REST and MCP

Payroll and tax API for Vietnam: REST and MCP server

The calculations behind our salary calculator, open to code and AI assistants: a REST API and a remote MCP server. No key and no sign-up. Every response lists the acts it used, notes on what is not covered and the data version.

02 — Start

Quick start

MCP server URL. Add it as a remote (custom) MCP server in your client:

https://since98.vn/api/mcp/payroll

Or call the REST API directly (POST keeps the salary out of server logs):

curl -X POST "https://since98.vn/api/v1/payroll/gross-to-net" \
  -H "Content-Type: application/json" \
  -d '{"gross":50000000,"region":"I","dependents":0,"as_of":"2026-03"}'
OpenAPI: /api/v1/payroll/openapi.json
03 — Short answers

How it works

How do I connect the payroll calculations to an AI assistant?

Short answer
Add a remote MCP server with the URL https://since98.vn/api/mcp/payroll. It uses Streamable HTTP, needs no key and no sign-in, and exposes 9 read-only tools.
How we do it
The server is stateless: every POST is answered on its own, without sessions. Current clients and older clients that start with initialize are both supported. Tools return structured content with an output schema.
Limits
60 requests per minute and 2,000 per day per IP address, shared with the REST API and the address tools. Dates before January 2026 are rejected. Results are reference calculations.
04 — Clients

Connect the MCP server

  1. Claude (web and desktop app)

    1. Open Customize → Connectors, choose “+ Add” → “Add custom connector”. On Team and Enterprise plans, an owner adds it in Organization settings → Connectors.
    2. Enter a name, for example Vietnam payroll, and the URL https://since98.vn/api/mcp/payroll.
    3. Choose “No sign in” for authentication and click Add.
    4. In a chat, ask for example: “What is the net salary for 40 million VND gross in region I with one dependent?”
    Client documentation
  2. Claude Code

    1. Run the command below in a terminal.
    2. Check the connection with /mcp inside a session.
    Terminal
    claude mcp add --transport http since98-payroll https://since98.vn/api/mcp/payroll
    Client documentation
  3. Cursor

    1. Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
    2. Reload the MCP list in Cursor settings.
    mcp.json
    {
      "mcpServers": {
        "since98-payroll": {
          "url": "https://since98.vn/api/mcp/payroll"
        }
      }
    }
    Client documentation
  4. VS Code (GitHub Copilot)

    1. Open the Command Palette and run “MCP: Add Server”.
    2. Choose HTTP, paste https://since98.vn/api/mcp/payroll and give the server an ID, for example since98-payroll.
    3. Use it in Copilot Chat in agent mode.
    Client documentation
  5. Windsurf

    1. Add the server to ~/.codeium/windsurf/mcp_config.json.
    2. Refresh the MCP servers in Cascade.
    mcp_config.json
    {
      "mcpServers": {
        "since98-payroll": {
          "serverUrl": "https://since98.vn/api/mcp/payroll"
        }
      }
    }
    Client documentation
  6. ChatGPT

    1. On chatgpt.com, open the plugins page and choose “+” → “Add custom MCP server”.
    2. Paste https://since98.vn/api/mcp/payroll as the server URL and choose no authentication.
    3. Availability depends on your ChatGPT plan and workspace settings.
    Client documentation
  7. Any other MCP client

    1. Add a remote (custom) MCP server by URL: https://since98.vn/api/mcp/payroll.
    2. Transport: Streamable HTTP. No key, no OAuth, no headers needed.
05 — Tools

MCP tools

This list is generated from the same definitions the server registers, so it matches what tools/list returns.

gross_to_netGross to net salary (Vietnam)
Calculate monthly take-home pay from a gross salary in Vietnam: employee social (8%), health (1.5%) and unemployment (1%) insurance with the ceilings for the date and region, family deductions (15.5 million VND for the taxpayer, 6.2 million per dependent), personal income tax by bracket (5-bracket scale 5% to 35%, or 20% flat for non-residents), net pay, and the employer contributions and total cost. Options: as_of (YYYY-MM or YYYY-MM-DD, default today; month and date are accepted as synonyms), region I-IV or 1-4 (default I), dependents (residents only), residency resident|non_resident, nationality vietnamese|foreigner (foreigner = contract of 12 months or more: no unemployment insurance), insurance_base (if the insured salary differs from gross; not below the regional minimum), union_member (0.5% member fee, default false). Examples: {"gross":30000000}; {"gross":50000000,"dependents":2,"as_of":"2026-08","region":"II"}; {"gross":120000000,"nationality":"foreigner"}.
net_to_grossNet to gross salary (Vietnam)
Find the gross monthly salary that gives a desired net (take-home) pay in Vietnam, for offers quoted in net. Exact to the dong: target_net and net_difference show the match. Returns the same breakdown as gross_to_net (insurance by fund, deductions, tax by bracket, employer cost). Options: as_of (YYYY-MM or YYYY-MM-DD, default today; month and date are accepted as synonyms), region I-IV or 1-4 (default I), dependents (residents only), residency resident|non_resident, nationality vietnamese|foreigner (foreigner = contract of 12 months or more: no unemployment insurance), insurance_base (if the insured salary differs from gross; not below the regional minimum), union_member (0.5% member fee, default false). Examples: {"net":25000000}; {"net":40000000,"dependents":1,"as_of":"2027-02"}.
pit_onlyPersonal income tax by bracket (Vietnam)
Calculate Vietnamese personal income tax on a monthly taxable income that is already known (salary after compulsory insurance and family deductions), with the amount and tax of each bracket of the 5-bracket scale (5%, 10%, 20%, 30%, 35%; thresholds 10, 30, 60, 100 million VND). For non-residents: flat 20% of the income. Use gross_to_net instead when you start from a gross salary. Examples: {"taxable_income":24500000}; {"taxable_income":80000000,"as_of":"2026-03"}; {"taxable_income":50000000,"residency":"non_resident"}.
employer_costEmployer cost of a salary (Vietnam)
Calculate what a monthly gross salary costs an employer in Vietnam: social insurance (sickness and maternity 3%, retirement 14%, occupational accident 0.5%), health insurance 3%, unemployment insurance 1% (not for foreigners), the 2% trade union fund, and the total cost; the employee's net pay is included. Options: as_of (YYYY-MM or YYYY-MM-DD, default today; month and date are accepted as synonyms), region I-IV or 1-4 (default I), dependents (residents only), residency resident|non_resident, nationality vietnamese|foreigner (foreigner = contract of 12 months or more: no unemployment insurance), insurance_base (if the insured salary differs from gross; not below the regional minimum), union_member (0.5% member fee, default false). Examples: {"gross":20000000}; {"gross":80000000,"nationality":"foreigner","as_of":"2026-08"}.
minimum_wageRegional minimum wage (Vietnam)
Return Vietnam's regional minimum wages (monthly and hourly, regions I-IV) in force on a date from January 2026, including the new rates from 1 January 2027, with the unemployment insurance ceiling of each region (20 x the minimum). The region of a workplace is set by the decree's annex of communes; this tool does not look it up. Examples: {}; {"as_of":"2027-02","region":"I"}.
withholding_10pct10% tax withholding without a labour contract (Vietnam)
Calculate the 10% personal income tax an organisation withholds from a payment to a resident individual without a labour contract or with a contract under 3 months (freelance, service fees). Threshold per payment: 2 million VND before 1 July 2026, 5 million VND from that date (the effective date of Decree 253/2026/ND-CP); below it nothing is withheld. Caveat on the date: the decree also applies its provisions on residents' salary income to the whole tax year 2026, so the 5 million threshold may be read as applying from 1 January 2026; this is not confirmed, and for January-June 2026 the tool uses 2 million and says so in the notes. Notes cover the commitment-form exemption. Examples: {"amount":8000000}; {"amount":3000000,"as_of":"2026-03-15"}.
bhxh_lump_sumOne-time social insurance payment (BHXH một lần)
Estimate the one-time social insurance payment in Vietnam: 1.5 months of the average insurance salary for each year of contributions before 2014 and 2 months for each year from 2014; leftover months round to half or a full year; under one year it is the amount contributed, capped at 2 months of the average. Pass salary_history (years with monthly insurance salary; each year is indexed with the published BHXH coefficients) or an already indexed average_salary with months_before_2014 and months_from_2014. Eligibility is not checked. Examples: {"salary_history":[{"year":2012,"monthly_salary":5000000},{"year":2013,"monthly_salary":6000000},{"year":2025,"monthly_salary":15000000,"months":7}],"as_of":"2026-09"}; {"average_salary":12000000,"months_before_2014":30,"months_from_2014":50}.
amount_in_wordsAmount in words (Vietnamese and English)
Write a whole number or VND amount (0 to 10^15) in words, in Vietnamese (as on invoices and payment orders: lẻ or linh for a zero tens digit, mốt, tư, lăm; nghìn, triệu, tỷ; optional "đồng chẵn") and in English. Examples: {"amount":1234567891}; {"amount":105,"language":"vi","vi_zero":"linh"}; {"amount":25000000,"vi_chan":true,"capitalize":true}.
data_infoParameters, acts and coverage
Return the parameters this calculator uses for each period from January 2026 (tax scale, family deductions, base salary, insurance ceilings, regional minimum wages, contribution rates, trade union rates, lump-sum rules, adjustment coefficients) with act numbers and verification status, the rounding rule, what is not included, and the data version. Use when the user asks how current or reliable the figures are. Takes no arguments: {}.
06 — REST

REST API

Every endpoint accepts GET with query parameters; endpoints that take amounts also accept POST with the same fields in a JSON or form body, and answer no-store. For salaries, use POST: a GET query string ends up in proxy and web-server logs, a request body does not. Amounts may contain digit separators (30.000.000 or 30,000,000). JSON responses, CORS open for any site. The REST endpoints and the MCP tools share the same input schemas and the same response format.

Endpoints
EndpointParametersMCP tool
GET, POST /api/v1/payroll/gross-to-netgross, as_of, month, date, region, dependents, residency, nationality, insurance_base, union_membergross_to_net
GET, POST /api/v1/payroll/net-to-grossnet, as_of, month, date, region, dependents, residency, nationality, insurance_base, union_membernet_to_gross
GET, POST /api/v1/payroll/pittaxable_income, as_of, month, date, residencypit_only
GET, POST /api/v1/payroll/employer-costgross, as_of, month, date, region, dependents, residency, nationality, insurance_base, union_memberemployer_cost
GET /api/v1/payroll/minimum-wageas_of, month, date, regionminimum_wage
GET, POST /api/v1/payroll/withholdingamount, as_of, month, datewithholding_10pct
GET, POST /api/v1/payroll/bhxh-lump-sumas_of, month, date, salary_history, average_salary, months_before_2014, months_from_2014, contributed_amountbhxh_lump_sum
GET, POST /api/v1/payroll/amount-in-wordsamount, language, currency, vi_chan, vi_zero, capitalizeamount_in_words
GET /api/v1/payroll/meta—data_info

Gross to net for a month before 1 July 2026 (insurance cap of that month)

curl -X POST "https://since98.vn/api/v1/payroll/gross-to-net" \
  -H "Content-Type: application/json" \
  -d '{"gross":50000000,"region":"I","dependents":0,"as_of":"2026-03"}'
Response (real output on the current data)
{
  "as_of": "2026-03-01",
  "region": "I",
  "residency": "resident",
  "nationality": "vietnamese",
  "dependents": 0,
  "gross": 50000000,
  "net": 42598600,
  "employee_contributions": {
    "lines": [
      {
        "fund": "social_insurance",
        "rate": 0.08,
        "base": 46800000,
        "amount": 3744000
      },
      {
        "fund": "health_insurance",
        "rate": 0.015,
        "base": 46800000,
        "amount": 702000
      },
      {
        "fund": "unemployment_insurance",
        "rate": 0.01,
        "base": 50000000,
        "amount": 500000
      }
    ],
    "total": 4946000
  },
  "pit": {
    "method": "progressive",
    "income": 50000000,
    "deductions": {
      "insurance": 4946000,
      "personal": 15500000,
      "dependents": 0,
      "dependents_amount": 0,
      "total": 20446000
    },
    "taxable_income": 29554000,
    "brackets": [
      {
        "bracket": 1,
        "from": 0,
        "to": 10000000,
        "rate": 0.05,
        "amount": 10000000,
        "tax": 500000
      },
      {
        "bracket": 2,
        "from": 10000000,
        "to": 30000000,
        "rate": 0.1,
        "amount": 19554000,
        "tax": 1955400
      }
    ],
    "tax": 2455400
  },
  "employer": {
    "lines": [
      {
        "fund": "social_insurance_sickness_maternity",
        "rate": 0.03,
        "base": 46800000,
        "amount": 1404000
      },
      {
        "fund": "social_insurance_retirement_survivorship",
        "rate": 0.14,
        "base": 46800000,
        "amount": 6552000
      },
      {
        "fund": "occupational_accident_disease",
        "rate": 0.005,
        "base": 46800000,
        "amount": 234000
      },
      {
        "fund": "health_insurance",
        "rate": 0.03,
        "base": 46800000,
        "amount": 1404000
      },
      {
        "fund": "unemployment_insurance",
        "rate": 0.01,
        "base": 50000000,
        "amount": 500000
      }
    ],
    "insurance_total": 10094000,
    "union_fund": {
      "fund": "trade_union_fund_kpcd",
      "rate": 0.02,
      "base": 46800000,
      "amount": 936000
    },
    "total": 11030000,
    "total_cost": 61030000
  },
  "insurance_base": {
    "requested_base": 50000000,
    "raised_to_minimum": false,
    "si_hi_base": 46800000,
    "ui_base": 50000000,
    "si_hi_ceiling": 46800000,
    "ui_ceiling": 106200000,
    "regional_minimum": 5310000
  },
  "notes": [
    "Social and health insurance base capped at 46800000 VND (20 x the base salary).",
    "For all of 2026 the 5-bracket scale and the 15.5 / 6.2 million VND family deductions apply (Law 109/2025/QH15 Art. 29(2): salary provisions apply from tax period 2026). Payers who withheld January-June 2026 under the old rules adjust in the 2026 annual finalization (Decree 253/2026/ND-CP Art. 70(2)).",
    "Employer trade union fund (KPCD) of 2% of the social insurance salary fund (Law on Trade Unions 50/2024/QH15 Art. 29(1)(b)); it is an employer cost, not deducted from the employee.",
    "Occupational accident and disease insurance at 0.5%. The reduced 0.3% rate (requires an approved application) and the draft decree reducing it to 0.3% are not applied.",
    "Region (I-IV) is chosen by the user; there is no locality-to-region lookup. The list of communes per region changes from 1 January 2027 (Decree 399/2026/ND-CP replaces Decree 293/2025/ND-CP).",
    "Not included: tax-exempt or capped allowances (meals, phone, uniform, stationery, per diem, housing), overtime and night-work pay, voluntary pension or life insurance, charity deductions. The whole gross amount is treated as taxable salary."
  ],
  "sources": [
    {
      "parameter": "regional_minimum_wage",
      "act": "293/2025/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/nghi-dinh-so-293-2025-nd-cp-46568/59713.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "si_hi_contribution_base_ceiling",
      "act": "41/2024/QH15 + 73/2024/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-41-2024-qh15-42576.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "ui_contribution_base_ceiling",
      "act": "74/2025/QH15 + 293/2025/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-74-2025-qh15-45562.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "contribution_rates_vietnamese_employee",
      "act": "41/2024/QH15; 51/2024/QH15 (Luật BHYT sửa đổi) + 188/2025/NĐ-CP; 74/2025/QH15 + 374/2025/NĐ-CP; 58/2020/NĐ-CP as amended by 158/2025/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-41-2024-qh15-42576.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "base_salary_luong_co_so",
      "act": "73/2024/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/nghi-dinh-so-73-2024-nd-cp-42169/50685.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "pit_resident_progressive_scale",
      "act": "109/2025/QH15",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-109-2025-qh15-468671.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "pit_family_deduction",
      "act": "110/2025/UBTVQH15",
      "url": "https://vanban.chinhphu.vn/?pageid=27160&docid=215927",
      "verified": "text_opened"
    },
    {
      "parameter": "pit_insurance_deductible",
      "act": "109/2025/QH15",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-109-2025-qh15-468671.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "trade_union_funding_employer_kpcd",
      "act": "50/2024/QH15",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-50-2024-qh15-43589.htm",
      "verified": "text_opened"
    }
  ],
  "data_version": "2026.11.21",
  "disclaimer": "Reference calculation only, not tax, legal or accounting advice. Verify the figures against the cited acts before relying on them."
}

Net to gross with one dependent

curl -X POST "https://since98.vn/api/v1/payroll/net-to-gross" \
  -H "Content-Type: application/json" \
  -d '{"net":30000000,"region":"I","dependents":1,"as_of":"2026-11"}'
Response (real output on the current data)
{
  "as_of": "2026-11-01",
  "region": "I",
  "residency": "resident",
  "nationality": "vietnamese",
  "dependents": 1,
  "target_net": 30000000,
  "net_difference": 0,
  "gross": 34007645,
  "net": 30000000,
  "employee_contributions": {
    "lines": [
      {
        "fund": "social_insurance",
        "rate": 0.08,
        "base": 34007645,
        "amount": 2720612
      },
      {
        "fund": "health_insurance",
        "rate": 0.015,
        "base": 34007645,
        "amount": 510115
      },
      {
        "fund": "unemployment_insurance",
        "rate": 0.01,
        "base": 34007645,
        "amount": 340076
      }
    ],
    "total": 3570803
  },
  "pit": {
    "method": "progressive",
    "income": 34007645,
    "deductions": {
      "insurance": 3570803,
      "personal": 15500000,
      "dependents": 1,
      "dependents_amount": 6200000,
      "total": 25270803
    },
    "taxable_income": 8736842,
    "brackets": [
      {
        "bracket": 1,
        "from": 0,
        "to": 10000000,
        "rate": 0.05,
        "amount": 8736842,
        "tax": 436842
      }
    ],
    "tax": 436842
  },
  "employer": {
    "lines": [
      {
        "fund": "social_insurance_sickness_maternity",
        "rate": 0.03,
        "base": 34007645,
        "amount": 1020229
      },
      {
        "fund": "social_insurance_retirement_survivorship",
        "rate": 0.14,
        "base": 34007645,
        "amount": 4761070
      },
      {
        "fund": "occupational_accident_disease",
        "rate": 0.005,
        "base": 34007645,
        "amount": 170038
      },
      {
        "fund": "health_insurance",
        "rate": 0.03,
        "base": 34007645,
        "amount": 1020229
      },
      {
        "fund": "unemployment_insurance",
        "rate": 0.01,
        "base": 34007645,
        "amount": 340076
      }
    ],
    "insurance_total": 7311642,
    "union_fund": {
      "fund": "trade_union_fund_kpcd",
      "rate": 0.02,
      "base": 34007645,
      "amount": 680153
    },
    "total": 7991795,
    "total_cost": 41999440
  },
  "insurance_base": {
    "requested_base": 34007645,
    "raised_to_minimum": false,
    "si_hi_base": 34007645,
    "ui_base": 34007645,
    "si_hi_ceiling": 50600000,
    "ui_ceiling": 106200000,
    "regional_minimum": 5310000
  },
  "notes": [
    "Employer trade union fund (KPCD) of 2% of the social insurance salary fund (Law on Trade Unions 50/2024/QH15 Art. 29(1)(b)); it is an employer cost, not deducted from the employee.",
    "Occupational accident and disease insurance at 0.5%. The reduced 0.3% rate (requires an approved application) and the draft decree reducing it to 0.3% are not applied.",
    "Region (I-IV) is chosen by the user; there is no locality-to-region lookup. The list of communes per region changes from 1 January 2027 (Decree 399/2026/ND-CP replaces Decree 293/2025/ND-CP).",
    "Not included: tax-exempt or capped allowances (meals, phone, uniform, stationery, per diem, housing), overtime and night-work pay, voluntary pension or life insurance, charity deductions. The whole gross amount is treated as taxable salary."
  ],
  "sources": [
    {
      "parameter": "regional_minimum_wage",
      "act": "293/2025/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/nghi-dinh-so-293-2025-nd-cp-46568/59713.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "si_hi_contribution_base_ceiling",
      "act": "41/2024/QH15 + 161/2026/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-41-2024-qh15-42576.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "ui_contribution_base_ceiling",
      "act": "74/2025/QH15 + 293/2025/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-74-2025-qh15-45562.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "contribution_rates_vietnamese_employee",
      "act": "41/2024/QH15; 51/2024/QH15 (Luật BHYT sửa đổi) + 188/2025/NĐ-CP; 74/2025/QH15 + 374/2025/NĐ-CP; 58/2020/NĐ-CP as amended by 158/2025/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-41-2024-qh15-42576.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "base_salary_luong_co_so",
      "act": "161/2026/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/nghi-dinh-so-161-2026-nd-cp-469550/65052.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "pit_resident_progressive_scale",
      "act": "109/2025/QH15",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-109-2025-qh15-468671.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "pit_family_deduction",
      "act": "110/2025/UBTVQH15",
      "url": "https://vanban.chinhphu.vn/?pageid=27160&docid=215927",
      "verified": "text_opened"
    },
    {
      "parameter": "pit_insurance_deductible",
      "act": "109/2025/QH15",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-109-2025-qh15-468671.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "trade_union_funding_employer_kpcd",
      "act": "50/2024/QH15",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-50-2024-qh15-43589.htm",
      "verified": "text_opened"
    }
  ],
  "data_version": "2026.11.21",
  "disclaimer": "Reference calculation only, not tax, legal or accounting advice. Verify the figures against the cited acts before relying on them."
}

Regional minimum wage from 1 January 2027

curl "https://since98.vn/api/v1/payroll/minimum-wage?as_of=2027-01"
Response (real output on the current data)
{
  "as_of": "2027-01-01",
  "effective_from": "2027-01-01",
  "effective_to": null,
  "regions": [
    {
      "region": "I",
      "monthly": 5700000,
      "hourly": 27400,
      "ui_ceiling": 114000000
    },
    {
      "region": "II",
      "monthly": 5080000,
      "hourly": 24400,
      "ui_ceiling": 101600000
    },
    {
      "region": "III",
      "monthly": 4450000,
      "hourly": 21400,
      "ui_ceiling": 89000000
    },
    {
      "region": "IV",
      "monthly": 4040000,
      "hourly": 19400,
      "ui_ceiling": 80800000
    }
  ],
  "notes": [
    "Region (I-IV) is chosen by the user; there is no locality-to-region lookup. The list of communes per region changes from 1 January 2027 (Decree 399/2026/ND-CP replaces Decree 293/2025/ND-CP).",
    "Parameters as known on 2026-11-21; changes adopted after that date are not reflected."
  ],
  "sources": [
    {
      "parameter": "regional_minimum_wage",
      "act": "399/2026/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/nghi-dinh-so-399-2026-nd-cp-470908.htm",
      "verified": "text_opened"
    },
    {
      "parameter": "ui_contribution_base_ceiling",
      "act": "74/2025/QH15 + 399/2026/NĐ-CP",
      "url": "https://congbao.chinhphu.vn/van-ban/luat-so-74-2025-qh15-45562.htm",
      "verified": "text_opened"
    }
  ],
  "data_version": "2026.11.21",
  "disclaimer": "Reference calculation only, not tax, legal or accounting advice. Verify the figures against the cited acts before relying on them."
}

Amount in words with «đồng chẵn»

curl -X POST "https://since98.vn/api/v1/payroll/amount-in-words" \
  -H "Content-Type: application/json" \
  -d '{"amount":1234567891,"vi_chan":true,"capitalize":true}'
Response (real output on the current data)
{
  "amount": 1234567891,
  "vi": "Một tỷ hai trăm ba mươi tư triệu năm trăm sáu mươi bảy nghìn tám trăm chín mươi mốt đồng chẵn",
  "en": "One billion two hundred thirty-four million five hundred sixty-seven thousand eight hundred ninety-one dong",
  "data_version": "2026.11.21",
  "disclaimer": "Reference calculation only, not tax, legal or accounting advice. Verify the figures against the cited acts before relying on them."
}
07 — Rules

Limits, privacy, dates and rounding

Limits

Each IP address can make 60 requests per minute and 2,000 per day, REST and MCP together, shared with the address tools. Over the limit, the REST API answers 429 with a Retry-After header, and the MCP server returns an error with the same wait time.

Need a higher volume, bulk processing of your own database, or these tools built into your system? Write to us at [email protected] or through the contact page.

Responses of minimum-wage, meta and openapi.json are publicly cacheable for a short time. Every endpoint that takes an amount is sent with Cache-Control: no-store, for GET and POST. Errors and 429 responses are not cached.

What we keep

The application does not save amounts or other input, in a database or in its logs. For the rate limit it keeps a counter per IP address in memory until the time window ends, and a daily count of calls per tool, saved in our database without IP addresses or inputs.

The logs of our web server and Cloudflare record technical request data (time, IP address, path), not the request body. A GET query string is part of the path and is logged with it, so send salaries with POST, in a JSON or form body; the calculator page does this. MCP requests are always POST.

API and MCP privacy

Dates and data version

Pass as_of as YYYY-MM or YYYY-MM-DD; without it the date is today in Vietnam. Each parameter is stored as periods, so a month before 1 July 2026 uses the old base salary and insurance cap, and a month from 1 January 2027 uses the new minimum wage.

Every response contains data_version, the acts used and a disclaimer. When an act changes a parameter, we update the dataset and the version changes; data_info returns all periods with their act, article and verification status.

Rounding and amounts

Amounts are whole VND. Each line (each fund's contribution for employee and employer, the tax of each bracket) is rounded to the nearest dong, halves up, and totals are sums of the rounded lines. Monthly amounts go up to 100,000,000,000 VND; amount_in_words takes 0 to 1,000,000,000,000,000.

Text fields in responses (notes, disclaimer) are in English. Region I to IV is an input: there is no lookup from address to region.

08 — Sources

Parameters and acts

Every figure the calculator uses is stored with its act, article, period and how we checked it. “Text opened” means we read the norm in the act itself; “secondary source” means we could not open the act and took the value from a reliable retelling.

Parameters and acts, data version 2026.11.21
ParameterAct and articlePeriodChecked
Tax scale for residents109/2025/QH15Điều 9 khoản 2 (biểu thuế); Điều 29 khoản 1 (hiệu lực 01/07/2026) và khoản 2 (quy định về tiền lương, tiền công của cá nhân cư trú áp dụng từ kỳ tính thuế năm 2026)from 1 January 2026Text opened
Family deductions110/2025/UBTVQH15Điều 1 điểm a, b; Điều 2 khoản 1 (hiệu lực 01/01/2026, áp dụng từ kỳ tính thuế năm 2026)from 1 January 2026Text opened
Insurance deducted before tax109/2025/QH15Điều 8 khoản 2from 1 January 2026Text opened
Tax rate for non-residents109/2025/QH15Điều 21from 1 July 2026Text opened
Tax rate for non-residents04/2007/QH12 (103/VBHN-VPQH)Điều 26 khoản 1to 30 June 2026Text opened
Insurance rates, Vietnamese employees41/2024/QH15; 51/2024/QH15 (Luật BHYT sửa đổi) + 188/2025/NĐ-CP; 74/2025/QH15 + 374/2025/NĐ-CP; 58/2020/NĐ-CP as amended by 158/2025/NĐ-CPSI: Luật BHXH Điều 32 khoản 1, Điều 33 khoản 1 điểm a, Điều 34 khoản 1. HI: ND 188/2025 Điều 6 khoản 1 điểm a (4.5%, employer 2/3, employee 1/3). UI: Luật Việc làm Điều 33 khoản 1 (tối đa 1%/1%) + ND 374/2025 Điều 4 khoản 1–2 (bằng 1%/1%). TNLĐ-BNN: ND 158/2025 Điều 43 khoản 2 điểm a (sửa khoản 1 Điều 4 ND 58/2020): 0.5% normal, 0.3% for qualifying enterprises (Điều 5 ND 58).from 1 January 2026Text opened
Insurance rates, foreign employees41/2024/QH15; Luật BHYT (22/VBHN-VPQH) + 188/2025/NĐ-CP; 74/2025/QH15; 158/2025/NĐ-CPSI coverage: Luật BHXH Điều 2 khoản 2; rates Điều 33 khoản 1, Điều 34 khoản 1 (both cover 'khoản 2 Điều 2'). HI coverage: Luật BHYT Điều 12 khoản 1 điểm c; rate ND 188 Điều 6 khoản 1 điểm a. TNLĐ: ND 158 Điều 43 khoản 2 (covers 'khoản 2 Điều 2'). UI: Luật Việc làm 2025 Điều 2 khoản 1 defines 'người lao động' as a Vietnamese citizen → foreigners not in UI.from 1 January 2026Text opened
Base salary161/2026/NĐ-CPĐiều 3 khoản 2; Điều 6 khoản 1–2from 1 July 2026Text opened
Base salary73/2024/NĐ-CPĐiều 3 khoản 2from 1 July 2024 to 30 June 2026Text opened
Social and health insurance cap41/2024/QH15 + 161/2026/NĐ-CPLuật BHXH Điều 31 khoản 1 điểm đ (trần 20 lần mức tham chiếu), Điều 141 khoản 13 (mức tham chiếu = lương cơ sở); ND 161 Điều 3 khoản 2from 1 July 2026Text opened
Social and health insurance cap41/2024/QH15 + 73/2024/NĐ-CPLuật BHXH Điều 31 khoản 1 điểm đ, Điều 141 khoản 13; ND 73/2024 Điều 3 khoản 2from 1 July 2025 to 30 June 2026Text opened
Unemployment insurance cap74/2025/QH15 + 399/2026/NĐ-CPLuật Việc làm Điều 34 khoản 2; ND 399 Điều 3 khoản 1from 1 January 2027Text opened
Unemployment insurance cap74/2025/QH15 + 293/2025/NĐ-CPLuật Việc làm Điều 34 khoản 2; ND 293 Điều 3 khoản 1from 1 January 2026 to 31 December 2026Text opened
Regional minimum wage399/2026/NĐ-CPĐiều 3 khoản 1; điều khoản hiệu lực: hiệu lực 01/01/2027, ND 293/2025 hết hiệu lựcfrom 1 January 2027Text opened
Regional minimum wage293/2025/NĐ-CPĐiều 3 khoản 1; điều khoản hiệu lực: hiệu lực 01/01/2026, ND 74/2024 hết hiệu lựcfrom 1 January 2026 to 31 December 2026Text opened
Trade union fund (employer)50/2024/QH15Điều 29 khoản 1 điểm b; Điều 30 (miễn, giảm, tạm dừng); hiệu lực 01/07/2025 (Điều 37)from 1 July 2025Text opened
Union member fee61/QĐ-TLĐ (Tổng Liên đoàn Lao động Việt Nam)from 1 July 2025Secondary source
10% withholding without a labour contract253/2026/NĐ-CPĐiều 50 khoản 2; Điều 69 khoản 1 (hiệu lực 01/07/2026)from 1 July 2026Text opened
10% withholding without a labour contract111/2013/TT-BTCĐiều 25 khoản 1 điểm i (not opened)to 30 June 2026Secondary source
One-time social insurance payment rules41/2024/QH15Điều 70 khoản 1, 2, 3, 5; Điều 72 khoản 2; Điều 73 khoản 2; Điều 5 khoản 6from 1 July 2025Text opened
Salary adjustment coefficients340/BHXH-CSXH (Bảo hiểm xã hội Việt Nam, February 2026)legal basis: ND 158/2025/NĐ-CP Điều 16 (formula: CPI of the year before the benefit year / CPI of year t, base 1994; rounded to 2 decimals; minimum 1) and Điều 45 khoản 2 điểm b (BHXH VN publishes annually)from 1 January 2026Secondary source

Reference calculation, not tax, legal or accounting advice. Check the figures against the acts before you rely on them.

09 — FAQ

Developer questions

Do I need an API key?

No. Both the REST API and the MCP server are open and read-only; only the per-address rate limit applies.

Why does net_to_gross return net_difference?

Net grows in steps of at most one dong, so the smallest gross that reaches the target net usually matches it exactly; net_difference shows the gap, normally 0.

How are foreigners and non-residents handled?

nationality=foreigner drops unemployment insurance (our reading of Employment Law 74/2025/QH15, stated in the notes); residency=non_resident applies 20% of gross with no deductions.

Where is the machine-readable description?

The OpenAPI document is at /api/v1/payroll/openapi.json. MCP clients get the tool input and output schemas from tools/list.

10 — Contact

Questions and data errors

Found a figure that does not match an act, or need a different limit for a project? Write to us; one of the founders replies.