Ask any retailer in Saudi Arabia where their day quietly leaks money, and sooner or later someone mentions the card machine.
Not because it fails. It works fine. The problem is that it sits next to the point of sale rather than inside it. The cashier reads a total off one screen and types it into another. Most of the time that's fine. Occasionally it isn't — a transposed digit, a rushed queue, a customer charged 45.00 instead of 54.00. At the end of the day the POS says one thing and the settlement report says another, and someone spends an hour with two printouts and a calculator working out which is right.
We've now connected Alhamrani Universal's mada terminals directly to ERPNext, so that stops happening.
What changes at the counter
The cashier rings up the sale as usual and selects card payment. The amount appears on the terminal by itself. The customer taps or inserts, enters a PIN if required, and the terminal talks to Saudi Payments as it always has.When approval comes back, the sale completes and the invoice is submitted — with the approval code, the retrieval reference number, the card scheme, the masked card number and the terminal ID all written onto it automatically.
Nobody types an amount. Nobody copies a reference number off a slip. There is no step where the two systems can disagree, because there is only one number and it travels between them electronically.
For the cashier, it's roughly one fewer thing to do per card sale. For the person closing the shift, it's the difference between reconciling and merely confirming.
What changes at the back office
Every card transaction becomes a record in ERPNext, linked to its invoice, with the approval code and reference number attached.That sounds mundane until the first chargeback query arrives, or a customer returns three weeks later insisting they paid by card and can't find the receipt. Instead of digging through terminal journals, you search the invoice.
Refunds inherit the same benefit. A mada refund has to reference the original transaction, and getting that reference by hand means finding the original receipt. Here it's already on the invoice, so the refund carries the correct reference without anyone hunting for it.
Month-end reconciliation stops being an exercise in matching two independent records, because there is only one record with two sides to it.
Built for cloud POS, not just cloud-hosted POS Most terminal integrations assume the POS software is installed on the till PC. Plenty of retailers have moved past that: the POS runs in a browser, hosted centrally, and the till is just a machine with Chrome on it.That creates a genuine architectural problem. A card terminal on a shop counter in Dammam is not reachable from a server in a datacentre, and it shouldn't be.
Our integration is built for exactly this. The connection to the terminal is made locally, at the counter, by a small service Alhamrani provides for the till PC. The ERPNext instance never touches the terminal and never needs to — which means this works on Frappe Cloud, on a managed private instance, or anywhere else your ERPNext happens to live, without opening a single inbound port into the shop's network.
Each till talks to its own terminal. Nothing routes through a central server, so nothing breaks when the internet is slow.
The part most integrations don't talk about Card payments fail in a specific and awkward way, and it's worth being direct about it.Sometimes a card is approved at the terminal and the confirmation never gets back to the POS. The network hiccups, the connection drops, the terminal is mid-reply when something interrupts it. The customer's account has been debited. The POS has no idea.
If the software treats that silence as a decline, the cashier takes payment again and the customer is charged twice. Those are the double-charges that turn into complaints, refunds and a difficult phone call — and they are entirely a software design problem, not a terminal problem.
We handle it as a distinct outcome. A declined card is one thing: nothing was charged, and taking payment again is safe. An unconfirmed payment is something else: it may have gone through, so the system stops and asks.
The cashier gets a clear instruction — check the terminal screen or print its last receipt — and two options. If the terminal shows an approval, she records it, and the sale completes using the payment already taken. The customer isn't asked to pay twice. If there's no approval, she records that instead and takes payment again with confidence.
Until she answers, the invoice will not submit. That's deliberate. An unresolved card payment is precisely the thing that should not be allowed to quietly disappear into the day's takings.
We'd rather ask the cashier one awkward question than send a customer an unexpected debit.Guardrails that matter in a real shop A few things we built because retail is messier than a specification.Where terminals are on the shop network rather than plugged into the till, every PC can technically reach every terminal. A wrong address in a configuration file doesn't fail — it succeeds against the wrong card machine, and a customer at the other end of the shop is asked to pay for someone else's basket. So each till verifies the terminal's identity when the POS opens, and refuses to trade if it doesn't match.
If the terminal isn't reachable, card payments are disabled and cash keeps working. A card machine problem shouldn't close the till.And every response from the terminal is checked against what was actually requested — the amount, the till number, the reference — before it's accepted as an approval. A response that arrives isn't automatically a response that belongs to this sale.
Alongside ZATCA, not instead of it Saudi retailers already carry e-invoicing obligations, and we've been doing ZATCA compliance work since Phase 1. The card details this integration captures sit alongside the ZATCA requirements on the same invoice and the same printed receipt — not as a second system to maintain.
If you're already running our ZATCA integration, this slots in beside it. What it takes to deploy Modest, in practice.
Alhamrani enables ECR mode on your terminals — this is a request to their support team and typically the longest lead time in the project, so worth starting early. Each till PC needs Alhamrani's local service installed, which is a small install and a one-time job. Terminals connect by USB or over the shop network, depending on the model you have. And each till is mapped to its terminal in ERPNext so the right counter drives the right card machine.We handle the ERPNext side, coordinate with Alhamrani on the terminal enablement, and work with your IT on the network requirements.
Talk to us We've been building on Frappe and ERPNext across Saudi Arabia, Qatar and the UAE for years, with a particular focus on the compliance and payments work that Gulf retail actually demands — ZATCA e-invoicing, mada payments, Arabic invoicing and POS at scale.
If your card machine and your point of sale are still two separate systems that happen to sit next to each other, we should talk.
ERPGulf — support@erpgulf.com · www.erpgulf.com
