Skip to content

Regional Compliance & Payments — Super Admin Setup Guide

Applies to: MERP25 · Subscriptions & Localization Module
Last updated: March 2026

Overview

The Regional Localization system allows the SaaS host to define "The Law of the Land" for each country. No user can register in a country that has not been explicitly configured and activated by the Super Admin.

Each region is defined by a RegionalGatewayConfig record, which contains: 1. Regional Tax Defaults (VAT, Corporate Tax rates, and thresholds). 2. Regional Payroll Defaults (Pension/Labor law settings). 3. Regional Payment Gateways (Stripe/PayPal API keys).

Step 1 — Access the Regional Setup Dashboard

  1. Log into the application as a Super Admin.
  2. Navigate to Control Panel → Regional setup (or go to /super-admin/regional-gateways).
  3. You will see a list of currently configured countries.

Step 2 — Add/Update a Region

To support a new country (e.g., France):

  1. Click Add Region (or click Edit on an existing one).
  2. Country Code: Enter the 2-letter ISO code (e.g., FR, AE, GB).
  3. Is Active: ✅ checked. If unchecked, signups from this country will be blocked.

Step 3 — Configure Regional Defaults (JSON)

Use the built-in JSON editors to define the compliance rules.

Tax Configuration

Define standard VAT and Corporate Tax rules. These are used for all automated reports.

{
  "vat_rate": 5.0,
  "corporate_tax_rate": 9.0,
  "corporate_tax_threshold": 375000,
  "currency": "AED"
}

Payroll & Compliance

Define regional labor law defaults (used by the HRMS/Payroll modules).

{
  "pension_rate": 5.0,
  "pension_threshold": 10000,
  "standard_working_hours": 40
}

Step 4 — Configure Regional Payment Gateway

This is how you receive subscription payments from users in this region. You can configure multiple providers, but usually, one (Stripe) is active.

  1. Provider: Select Stripe or Paypal.
  2. API Config (Encrypted): Enter the API keys for this region.

[!IMPORTANT] These keys are stored in the database to configure the integration for the region.

Stripe Config Example: 

{
  "public_key": "pk_live_...",
  "secret_key": "sk_live_..."
}

Step 5 — Verify the Signup Block

  1. Log out and go to the Signup Page (/register).
  2. Select the country you just configured.
  3. Click Continue.
  4. The system should allow you to proceed to Step 2.

[!NOTE] If you select a country that is not in the Super Admin list (or is set to Inactive), the "Continue" button will show an error: "Registration is not supported in this region."

Step 6 — Tenant Overrides (Company Admin)

If a specific company has a tax exemption (e.g., a Free Zone company in the UAE with 0% Corporate Tax), the Company Admin can override your regional defaults:

  1. Company Admin goes to Admin → Localization.
  2. Under Corporate Tax, they click Create Custom Override.
  3. They set their custom rate (e.g., 0.00).
  4. The system will now use 0% for their reports instead of your regional 9%.

Troubleshooting

Issue Likely Cause Fix
Signup blocked for a country No active RegionalGatewayConfig found Add/Activate the country in the Super Admin dashboard (Step 2).
Tax reports showing 0% or error Missing tax_config in Regional setup Ensure the JSON in Step 3 is valid and contains vat_rate.
Payment fails during checkout Incorrect API keys for the region Verify the encrypted keys in Step 4 match the region's Stripe account.