🤖 Explain with AI

Tax & compliance¶

4Geeks Payroll applies the rates of one country per workspace: the country you choose in Settings → Business. This page explains the proposed packs, the client signature that unlocks payment and the checklist the console verifies.

The compliance country¶

The console takes the country from Settings → Business (company_profiles.country) and mirrors it into the payroll settings. There is no separate country selector in Tax & Compliance: what you see is the compliance country.

• Owner and workspace admins are the only ones who can change it.
• 18 LATAM countries are supported: Argentina, Bolivia, Brazil, Chile, Colombia, Costa Rica, Dominican Republic, Ecuador, Guatemala, Honduras, Mexico, Nicaragua, Panama, Peru, Paraguay, El Salvador, Uruguay and Venezuela.
• A non-LATAM country leaves the compliance country empty. Payroll then shows the “set the business country” banner and cannot apply rates.
• New employees inherit the country from the database trigger, including CSV imports and API writes. Existing employees are not rewritten silently: the console shows the mismatch and offers Align N employees, an explicit and audited action.
• Changing the country is blocked while the workspace still has employees, tax rows, income-tax tables or draft runs of the previous country (PAYROLL_COMPLIANCE_COUNTRY_LOCKED, with the counts in the error detail). Align the employees, remove the previous country’s configuration (Settings → Payroll → Tax & Compliance shows the dormant rows) and save again.

The proposed packs¶

Each country ships a proposed general-regime pack. The rates are a starting point the company reviews, edits if needed and signs; 4Geeks does not certify them.

Each pack expands into individual line items (for example CCSS/IVM in Costa Rica, IMSS/INFONAVIT in Mexico, AFP/ISAPRE in Chile, INSS/FGTS in Brazil) that you can review, edit or delete.

Income tax¶

The console withholds salary income tax when the country has a table in force:

• 17 bundled tables (Argentina, Bolivia, Brazil, Chile, Colombia, Costa Rica, Dominican Republic, Ecuador, Guatemala, Honduras, Mexico, Nicaragua, Panama, Peru, Paraguay, El Salvador, Uruguay). Venezuela has no proposed table: add your own and sign it.
• Base after social security: for most countries the taxable base is the gross minus the employee’s contributions of the same payment. Costa Rica keeps the gross base.
• Family amounts: they can be a tax credit on the computed tax (Costa Rica) or a deduction from the taxable base (Argentina).
• Currency: the table only applies when its currency matches the payroll currency. The screen warns when they differ (for example a Costa Rica workspace paying in USD) and the tax is not withheld until they match.

Edit or add a table in Tax & Compliance → Salary income tax. New versions keep history: a table applies from its effective date and never rewrites previous payslips.

Install or restore the pack¶

When you set or change the business country, the console installs the proposed pack automatically: social-security rows, the income-tax table and the holidays of the year. It never overwrites rows that already exist for that country.

If you edited the rows and want the proposal back, use Restore proposed rates. The pack version, its public sources and the reference minimum wage are shown on the country card.

The client signs the rates¶

Payment is locked until the company signs the rates it is going to use.

1. Click Review and sign.
2. Check every rate, cap, progressive bracket and the income-tax table.
3. Type the full name of the person signing, add an optional note and confirm the responsibility statement.
4. The console stores the signature with the server-computed hash of the exact rows, the name, the user, the email, the role and the date. It also appears in the audit trail.

If any rate or table changes afterwards, the signature becomes stale and the console asks for a new one. The hash is calculated by the database (payroll_compliance_config_hash), never by the browser, so the signature covers exactly what payroll uses.

The compliance checklist¶

The checklist is computed from the workspace data, not hardcoded. It flags:

• the compliance country missing or unsupported;
• the pack not installed, or with no employee/employer rows;
• no income-tax table for the country;
• the income-tax table currency not matching the payroll currency;
• active employees from another country (with the Align action);
• holidays of the year not loaded;
• the rates not signed or the signature stale.

Errors block payment; warnings are recommendations. Fix them before running payroll.

Electronic filings¶

The same screen lists the periodic filings of the country: due dates, status, agency reference and acknowledgement. Costa Rica’s CCSS SICERE file is generated by the console (records 25, 35 and 15) and INS has an API connector. See Electronic filings for the step-by-step and the country-by-country channel.

Troubleshooting¶

FAQ¶

Related¶

• Payroll settings
• Electronic filings
• Payroll runs
• Country reference

Still have questions? Ask on Discord or explore the tutorials.