ZATCA, Nafath, Mada and ERP integrations
We connect the systems a Saudi product cannot launch without: ZATCA Phase 2 e-invoicing, Nafath identity, Mada card payments, and the ERP or CRM your finance team already runs. Built, tested against the vendor sandbox, and monitored after launch.
Every integration is scoped on its own line, with its own acceptance test and its own owner in the plan.
The integration is what decides the launch date
A portal can be designed, built and reviewed on schedule, then sit for weeks because the e-invoicing certificate was not issued, the acquirer had not approved the merchant account, or the ERP vendor would not open a sandbox.
We plan integrations first, not last. Before design starts we know which system is the record of truth, which credentials already exist, who owns them, and what the acceptance test is.
That order is why a build with four integrations can still hold a date.
What we connect
Four systems, four different failure modes
Each one has its own onboarding, its own sandbox and its own way of failing in production. We treat them as four separate deliveries inside one project.
ZATCA Phase 2 e-invoicing
Onboarding on the Fatoora platform, cryptographic stamping, UBL 2.1 XML, QR codes, and clearance or reporting through ZATCA APIs.
- CSR, compliance CSID and production CSID
- Standard invoices cleared before they reach the buyer
- Simplified invoices reported within 24 hours
- Retry queue so an outage does not lose an invoice
Nafath national identity
Login through the National Single Sign-On flow: the user identifies themselves, approves a two-digit request in the Nafath app, and your system receives a verified identity.
- OAuth 2.0 and OIDC against NSSO
- Role mapping from the returned identity
- Session and logout handling in Arabic and English
- A fallback path for users without a Nafath account
Mada and card payments
Card payments through a licensed Saudi acquirer or gateway, with 3-D Secure and the reconciliation your finance team needs.
- Mada, Visa and Mastercard through one gateway
- 3-D Secure authentication
- Webhook handling for refunds and partial captures
- Settlement report that matches your ledger
ERP and CRM
The portal reads from your system of record instead of keeping a second copy. Where there is an API we use it; where there is not, we use a scheduled sync or a secure database link.
- SAP, Microsoft Dynamics, Odoo, Zoho or a custom ERP
- Field mapping agreed in writing before build
- Idempotent writes so a retry cannot duplicate an order
- Monitoring that names the failing record, not just the endpoint
How it ships
How an integration gets to production
The same four gates on every integration, whether it is an e-invoice or a payment.
- 01
Access map
We list every system, who owns it, which credentials exist and which need to be requested. Most delays are found here, before they cost a sprint.
- 02
Sandbox first
We build against the vendor test environment and record the acceptance cases with you. A demo against mocked data does not count.
- 03
Reconciliation
Every write is checked against the system of record: totals, statuses, duplicates. Finance signs off on a full day of transactions before launch.
- 04
Monitoring and handover
Alerts on failed calls, expiring certificates and queue depth. You get the runbook and the credential owner list at handover.
Where integrations fail after launch
None of these are code problems on day one. All of them are planned for.
- Certificate expiry
- ZATCA and payment credentials expire. The expiry date goes into monitoring with a 30-day warning, not into a spreadsheet.
- Sandbox is not production
- Rate limits, payload sizes and error codes differ. We run a production pilot with a small number of real transactions before full cutover.
- Duplicate writes
- A timeout does not mean the write failed. Every call carries an idempotency key so a retry cannot create a second invoice or order.
- Mapping drift
- The ERP adds a field or changes a tax code. The mapping is versioned in the repository, so a change is reviewed rather than patched in production.
Integrations already in production
Payment gateways shipped in DAMEN, a Saudi e-commerce trust and escrow platform, and Wafra, a Saudi marketplace for local sellers. ZATCA Phase 2, Nafath, Mada and ERP connections are delivered the same way: scoped, tested against the vendor sandbox and monitored after launch.
- Integration types delivered: e-invoicing, identity, payments, ERP
- 4
- Saudi platforms in the portfolio with a shipped payment gateway
- 2
- Weeks for a portal MVP with one integration, from kickoff
- 6–12
Both projects are listed in the portfolio with the technologies we shipped.
Questions buyers ask before scoping
Do you integrate ZATCA Phase 2 e-invoicing?
Yes. We handle onboarding on the Fatoora platform, CSR and CSID generation, UBL 2.1 XML, QR codes, and clearance or reporting. The acceptance test is a real invoice cleared by ZATCA, not a sandbox response.
Can you connect an ERP that has no API?
Usually. We use a scheduled sync against a staging schema, a secure database link, or file exchange where the vendor supports it. The constraint is written into the scope before build.
Who owns the integration credentials?
You do. Certificates, API keys and acquirer accounts are registered in your name. We work with delegated access and hand over the credential owner list at launch.
How long does an integration take?
A single integration usually adds two to four weeks to a portal build, and the vendor onboarding is often the long pole. ZATCA and acquirer approvals run on their own schedule, so we start them in week one.
What happens if ZATCA or the gateway is down?
Calls go into a retry queue with exponential backoff, and the invoice or payment stays in a pending state your team can see. Nothing is marked complete until the other system confirms it.
Do you work with our existing integration vendor?
Yes. We can take over an existing integration, review it, or work alongside the vendor who owns the ERP. The access map records who does what so two teams do not write to the same field.
Send the systems, and we will map the integration
Tell us which systems have to talk to each other and who owns each one. We will come back with the access map, the vendor onboarding steps and a dated plan.
30 minutes, no obligation. If an integration is not worth building, we will say so.
