1. Executive Summary
This document sets out how Muqeem and Mudad can be integrated into your ERPNext system to automate two of the most time-consuming compliance workloads for any Saudi employer: managing expatriate residency documents (Muqeem) and paying salaries through the Wage Protection System (Mudad).
The integration is built natively on ERPNext by ERPGulf, the specialist ERPNext provider for the Gulf region. The functionality described below is delivered inside your own ERPNext instance, connected to your existing HR, Employee, and Payroll data, so there is no separate HR platform to license, learn, or reconcile against.
In practical terms, HR and finance teams will be able to issue and renew Iqamas, manage exit/re-entry and final exit visas, keep passport records current, and transfer payroll to employees through Mudad's bank channels — all from within ERPNext, without logging into separate government or banking portals for routine transactions.
2. What the Integration Delivers
At a high level, the two integrations cover distinct but complementary areas of Saudi compliance:
3. Muqeem — Residency & Immigration Management
Muqeem is the digital gateway to the Saudi Passports Directorate (Jawazat). It lets an employer carry out residency and travel-document transactions for expatriate staff electronically, instead of visiting government offices. Integrated into ERPNext, each transaction is driven from the employee's own record and the resulting government status is written back automatically.
3.1 What your team will be able to do
From within ERPNext, authorised users will be able to perform the following Muqeem actions:
• Issue an Iqama (residency permit)
• Renew an Iqama
• Transfer an Iqama
• Issue, cancel, extend, and reprint an Exit / Re-Entry Visa
• Issue and cancel a Final Exit Visa
• Extend the validity of a passport
• Renew a passport
Every completed action is recorded against the relevant employee, and the document status — Active, Expires Soon, or Expired — is kept current so the team always has a real-time view of workforce compliance.
3.2 How it will work inside ERPNext
The Muqeem functions are surfaced through the Employee and HR modules in ERPNext, organised so each document type has its own view:
• Iqama management — issue, renew, transfer, or register an existing Iqama, with the Iqama number, passport number, and passport expiry drawn directly from the employee's profile and written back if they change.
• Exit / Re-Entry Visas — issue, cancel, extend, and reprint; when a visa is extended, both the previous and the new duration are retained for audit.
• Final Exit Visas — issue and cancel, linked to the employee's off-boarding record.
• Passports — extend and renew, keeping the ERPNext employee record and the government record aligned.
Supporting documents such as the Iqama PDF can be uploaded and stored against the record. Once a transaction reaches Completed status, the record is locked to preserve an accurate audit trail.
3.3 Technical integration mechanism
Muqeem provides structured API access (offered through Elm's official integration channels, e.g. Rabet / Integrator). ERPGulf builds a direct server-to-server connector within ERPNext: when an HR user submits a transaction, ERPNext calls the Muqeem API endpoint using the establishment's official subscription credentials, processes the request, and pulls the updated government record straight back into ERPNext.
Because the connection is direct, there is no manual re-keying between systems and no separate portal to maintain for day-to-day work.
3.4 Alerts, roles, and reporting
• Expiry notifications — automated email alerts a configurable number of days before an Iqama expires, so renewals are never missed.
• Role-based access — full-access and read-only Muqeem roles can be assigned, so some users can act while others can only view.
• Event / audit log — every record sent to Muqeem is tracked and reviewable.
• Reporting — Iqama data can be pulled into ERPNext's report builder for custom compliance and expiry reports.
4. Mudad — Payroll & Wage Protection System (WPS)
Mudad is the centralised payroll and Wage Protection System platform supervised by MHRSD and SAMA. Its purpose is to ensure employees are paid the correct amount, on time, through authorised banking channels — and to flag late or partial payments as compliance violations. Mudad acts as a single hub connecting an employer to a growing list of Saudi bank channels. WPS submission is mandatory for all private-sector employers in Saudi Arabia, with no exemption by company size.
4.1 What your team will be able to do
• Subscribe and onboard the establishment to Mudad from within ERPNext
• Send an approved salary batch (payroll run) to Mudad for payment
• Set the transfer date and route payment through the authorised bank channel
• Track the status of every batch sent, and download batch details for reconciliation
• Cancel a Mudad transaction after submission where required
This replaces the manual routine of exporting a Salary Information File (SIF) from payroll and uploading it to the Mudad portal by hand each month.
4.2 How it will work inside ERPNext
Payroll continues to be calculated and approved in ERPNext exactly as it is today. Once a salary batch is finalised and locked, the user sends it to Mudad directly from the payroll batch screen and specifies the transfer date. ERPNext packages the batch and submits it through the authorised banking channel; the bank executes the transfer and forwards the official WPS file to Mudad on the back end. Batch status and event history are visible inside ERPNext, and batch details can be exported for reconciliation.
4.3 Technical integration mechanism
Mudad does not expose an open self-service API to third-party software. Integration is therefore achieved through the authorised corporate banking channel (Auto-WPS) — for example ANB, SAB, and other partner banks. In practice:
1. Payroll is calculated, approved, and locked inside ERPNext.
2. Instead of manually downloading a SIF and uploading it to the Mudad portal, ERPNext transmits the payment batch to the establishment's corporate bank, referenced against its National Unified Number.
3. The bank executes the salary transfer and automatically forwards the official WPS transmission file to Mudad on the back end.
4.4 Operational requirements
Two conditions must be met for reliable WPS submission, and both are built into the process:
• Name matching — employee names must match across ERPNext, Mudad, the employee's bank record, and GOSI. Mismatches are the most common cause of failed transfers and are checked before submission.
• Transfer date — the transfer date must always be the next business day or later, so the banking channel can process the payment instructions correctly.
5. Why Deliver This on ERPNext
Both integrations run inside your own ERPNext instance, built and supported by ERPGulf as the ERPNext specialist for Saudi Arabia. The advantages of this approach over a separate HR platform are:
• Single source of truth — Muqeem and Mudad act on the same employee and payroll data you already maintain in ERPNext; there is no second system to keep in sync.
• No additional HR platform to license — the capability is part of your ERP, not a bolt-on subscription to a third-party HR suite.
• Consistent with existing Saudi compliance — it sits alongside ERPNext capabilities already in use in the Kingdom, such as ZATCA e-invoicing and GOSI handling.
• Full audit trail — government and payroll transactions are logged against records inside the ERP, supporting inspections and reconciliation.
• Extensible — as ERPNext is open and locally supported, the connectors can be adapted as Muqeem, Mudad, and bank requirements evolve.
6. Prerequisites & Next Steps
To proceed, the following will be required from the client side:
• An active Muqeem establishment subscription with API/integration access (e.g. Elm Rabet / Integrator package) and credentials.
• An active Mudad subscription and a corporate bank account with a partner bank that supports Auto WPS submission.
• Establishment details: Commercial Registration Number (CRN), MLSD unified ID / National Unified Number, and an authorised signatory for Mudad.
• Clean, matched employee master data (names, Iqama numbers, passport details, IBANs, GOSI) in ERPNext.
On confirmation, ERPGulf will scope the connector build, configure the ERPNext modules, migrate and reconcile employee data, and run a controlled pilot before go-live. A detailed implementation plan, timeline, and commercials will follow this proposal.
Note: capabilities and connectivity depend on current Muqeem, Mudad, and partner-bank terms, which are set by the respective authorities and may change. Final scope will be confirmed against those requirements at the time of implementation.
