AFD: Fuel Dispenser Integration

An automated fuel dispenser cannot take a payment the way every other terminal does, because the amount is not known until after the fuel is delivered. The customer authorises a ceiling, pumps, and only then is the real figure available.

That makes AFD a two-message transaction — a pre-authorisation before the nozzle is released and a capture after it is returned — with a hold on the cardholder's money in between. Everything difficult about a forecourt lives in that gap.

This page is for the team building the FCS application — the app that runs alongside the
mada payment app on a Nami UN20 unattended terminal, drives the pump, and owns the customer
journey. It covers the mada AFD flow as specified in the SAMA mada AFD Framework v1.3
(Oct 2023), and it is self-contained. Everything an AFD integration needs is here, including
the app-to-app mechanics in sections 2 and 3 — a forecourt integrator should not have to read a
general integration guide and work out which half applies.

Note: Section 6 documents the screens from a working forecourt implementation. The
wording marked certified is fixed by the SAMA framework and audited; the rest is one
vendor's realisation, shown because the shape of it is worth copying.

Important: AFD is a certified integration. You cannot ship it and certify later — SAMA audits the customer journey, the screen wording in both languages, and every void and capture scenario in section 7. Build against that matrix from the start.

Start here: Who drives - or pick a section.

Contents

1. Who drives - Two applications on one terminal, and which of them owns the screen at each moment.
2. Talking to the payment app - The app-to-app handshake: the intent you send, the receiver the answer needs, and the manifest entries without which it silently never arrives.
3. Reading the response - The response fields, which are confirmed against production traffic, and why nothing past field 27 is safe to read by position.
4. The transaction types - Pre-authorisation, capture, void and reversal, and the codes that carry each one.
5. The amounts - The SAR 300 ceiling, minor units, and the three ways a customer settles on a figure.
6. The customer journey - Every screen in order, English and Arabic, and the one branch that decides what the payment app is asked to hold.
7. The scenario matrices - The audit script. Every row is a test you will be asked to demonstrate on a live pump.
8. What your application must survive - Holds that outlive your process, power lost mid-fuelling, and the capture message field by field.
9. Certification - What SAMA audits, what has to be submitted before an audit date exists, and why the scope is mada only.
10. Checklist - What to have working before asking for a certification slot.