Foundry · build sequence 01 Architecture → 02 Flow & Hierarchy → 03 Canonical Model
Paying.co · Foundry · Flow & Hierarchy · companion detail

How a transaction actually runs
— provisioning, then the universal lifecycle.

The detail layer beneath the architecture model. Two cycles: provisioning (what loads into the L2 kernel on first boot or parameter update) and the transaction lifecycle (tap → assembled canonical). Every step from engage to normalize is processor-independent — the adapter is only called once the work is already done.

device class IDT_NEO2 SDK 1.00.190 contactless-first real methods, not generic EMV
Cycle 1 · Provisioning runs on first load + every parameter-update push — never per-transaction
Hierarchy · what populates the kernel

A configure-then-verify cycle. Top of the hierarchy is the terminal's own identity; AIDs hang off configuration groups; keys sit beneath. Nothing here knows the processor — Santander doesn't decide which AIDs or floor limits you load. This whole cycle is core, processor-independent, and idempotent: same code reconciles desired-state vs. kernel-state whether it's boot or an update.

Level 1 · terminal identity & global config
Terminal Data
Country code, terminal type & capabilities, default currency & language. The device's baseline before any brand logic.
ctls_setTerminalData
Level 2 · enforced boundaries
Configuration Groups
Named bundles carrying the limits the L2 kernel enforces — floor limits, CVM-required limit, contactless transaction limit, and other boundaries. AIDs reference a group, so a deployment can vary limits without touching AID definitions.
ctls_setConfigurationGroupctls_getConfigurationGroup
Level 3 · accepted applications
Application Data · AIDs
Each accepted AID (Visa, Mastercard, Amex, Discover…) with its kernel config, linked to a configuration group from Level 2.
ctls_setApplicationData
Level 4 · offline-auth keys
CAPK & CRL
CA public keys per RID/index for offline data authentication, plus the certificate revocation list. Loaded, never implemented — the kernel does the crypto.
ctls_setCAPKemv_setCRL
Verify · the step most skip — and a cert-killer if missed
Read-back & Check-value
Read the kernel state back and confirm it matches intent. Provisioning isn't "done" until the configuration check-value matches the expected value. This is what makes the cycle trustworthy and idempotent.
ctls_retrieveTerminalDatactls_retrieveAidListctls_retrieveCAPKListemv_getEMVConfigurationCheckValue
Source ⇄ Service Your "interface or feed" instinct, resolved: split a Configuration Source (a versioned, signed parameter manifest — pulled from a host/config service, MDM-pushed, or a local profile) from a Provisioning Service that consumes it and drives set* → retrieve* → check-value idempotently. The manifest is data and can be deployment-specific (a transit kiosk's limits ≠ a retail terminal's). The loader is core. Both live above the processor boundary.
Cycle 2 · Transaction Lifecycle blue-sky · tap → assembled canonical → online → complete
The universal span · everything before the processor

Steps 1–5 are the answer to "what happens when a card taps." They are 100% processor-independent — engage, capture, handle decryption, parse TLV, normalize. The processor does not exist until step 6, and re-enters only to deliver its result in step 7.

▼ universal · core · reused every engagementnone of this knows who the acquirer is
01
Engage the readeruniversal
A start call arms the field and begins polling for a tap. You hand the kernel amount, currency, transaction type, timeout, and the tags you want returned. (Connection & poll-mode are established once at bind time.)
ctls_startTransactiondevice_setPollModedevice_setNEOGen
02
Capture the tap — event-drivenuniversal · async
No polling for the card. The kernel fires callbacks as the tap progresses — card detected, processing, then a completion event carrying the EMV payload. The state machine waits on these events; it never blocks. This is the async spine.
registerListenOnReceiverListener
03
Handle decryptionuniversal · crypto-insulated
P2PE / encrypted card data is encrypted by the reader under DUKPT — you do not implement the decryption. Data arrives structured; where a decrypt is needed it's a key-management concern (KSN + your P2PE zone, off-device HSM), behind the distilled crypto interface — not transaction-flow logic.
device_getKSN
04
Parse the TLV — helper layeruniversal
The result comes back as EMV TLV. Pure, reusable helpers (get-tag, walk, decode) lift the tags you care about — AID, AIP, ARQC, amount, currency, TVR, TSI, token. Heavily reused, processor-blind, and the input to the normalizer.
emv_retrieveTransactionResultcreateFastEMVDatadevice_getResponseCodeString
05
Normalize → canonicaluniversal · the seam
Parsed TLV becomes the canonical transaction object. Everything above spoke SDK + TLV; everything below speaks canonical. This object is the contract — produced here, consumed by the adapter. Design it first; everything is cast against it.
IDTEMVData → canonical
◆ processor boundary
06
Online authorization — the adapterprocessor · cast per acquirer
Now, and only now, the adapter enters: canonical → ISO 8583 / REST host message → processor → response parsed back to canonical. Each processor (Global Payments, TSYS TransIT, Elavon, Cybersource) is a separate casting from the same mold, bundling its own host library & key ceremony.
adapter: canonical ⇄ host
07
Complete back to the kerneluniversal
Feed the online result (ARPC, response code) back so the kernel finalizes, then retrieve the final state and display the outcome. Card-removal, cancel, timeout, and reset all handled here. Universal again — the processor's answer is just data flowing back through core.
ctls_displayOnlineAuthResultemv_completeTransactiondevice_getTransactionResultsdevice_cardRemovalDetection
◆ the load-bearing conclusion
Steps 1–5 and 7 are universal core. Only step 6 is the processor.

Everything that makes a transaction work — engage, capture, decrypt-handling, TLV parse, normalize, and the finalize back to the kernel — happens independent of the acquirer. The adapter is handed an already-assembled canonical transaction and asked one thing: get it authorized. That's why the canonical model is designed first — steps 1–5 all produce it, step 6 consumes it. It is the contract both sides are built against.