Who drives

Two apps, one device

The thing to fix in your head before anything else: there is one terminal and one screen.

A Nami UN20 unattended terminal at the pump runs two Android applications side by side:

They are not two boxes and not two screens. Both draw on the same display, and the customer
sees one machine: your app is in front for most of the journey, hands over to the payment app
for the card, and gets the screen back afterwards.

That is why the integration is app-to-app rather than a network protocol — the two are
processes on one device, and they talk by Android Intents. Section 2 covers the mechanics.

Where this guide says FCS app, it means your application and the screens it draws.
Payment app means the mada application. The distinction is about which application is in
front, not which piece of hardware — there is only one of those.

The pump is the master

Your FCS app is driven by the pump, and the payment app is driven by you.

Every transaction starts at the pump. The payment app does not decide to pre-authorise, does
not decide when to capture, and does not decide the amount — it receives a request from your
app, runs the card transaction, and reports the result back. Your app, in turn, acts on what
the pump tells it.

Three rules from the SAMA framework follow from that:

• One terminal per nozzle. A terminal is integrated to exactly one pump. This is audited.
• A pump is idle only when nothing is outstanding. If a pre-authorisation has been neither captured nor voided, that pump is not available to the next customer.
• If the link to the pump drops mid-fuelling, the terminal finishes the transaction itself. It cannot wait for an instruction that is not coming, because the money is already on hold.

---

Contents  ·  Talking to the payment app →