Appendixes
| Appendix | Title |
|---|---|
| Appendix-1 | Architecture Decision Record (ADR). |
| Appendix-2 | About services. |
| Appendix-3 | About Logger. |
| Appendix-4 | About ICS. |
ADR
This section documents decisions about architecture and decision to help readers understand how switstack moka is built.
| Decision #1 | EMV Level 2 Certifications |
|---|---|
| Context | EMVCo Books follow a writing pattern that helps to normalized EMV Level 2 implementations. But for a given brand, a C-x book diverges from the payment network's specification which imposes a dual reference complicating code documentation, design, and test plan realization. |
| Decision | switstack moka targets payment networks certifications, excepted for EMVCo contact and EMVCo Book C-8. |
| Consequences | No impact on EMVCo Book C-2 as the payment network aligned their specifications already. For other networks, code documentation refers to requirements coming from the payment networks specifications. |
Services
Each switstack moka's software component is a service that follows the same architecture pattern.
- A service is encapsulated by a proxy that can be reached by any other service through a message broker (the proxy is registered onto the message broker at the setup time);
- A service implements a set of generic services, and a set of functional services that are specific to the service.
- A service runs on top of a data model that rules service's states that generic and functional services navigate;
All services support the following generic services:
| Generic Service | Description |
|---|---|
| GENERIC_SERVICE_GET_NAME | -- |
| GENERIC_SERVICE_GET_IDENTIFIER | -- |
| GENERIC_SERVICE_GET_VERSION | -- |
| GENERIC_SERVICE_GET_CHECKSUM | -- |
| GENERIC_SERVICE_GET_SETUP | -- |
| GENERIC_SERVICE_GET_INITIALIZE | -- |
| GENERIC_SERVICE_SET_PARAMETERS | -- |
| GENERIC_SERVICE_GET_PARAMETERS | -- |
| GENERIC_SERVICE_GET_CLEANUP | -- |
| GENERIC_SERVICE_GET_RELEASE | -- |
Then, each service may expose a series of functional services depending on its purpose. The following sections present each service along with its data model.
HSM
Data model
Functional services
Entry Point
Data model
| Tag | Name | Type | Set | Get | Description |
|---|---|---|---|---|---|
| 0x87 | Priority indicator | Byte value [0..15] |  |
 |
Selected candidate' AID priority |
| 0x96 | Kernel identifer-terminal | TLV | |
|
Selected candidate's kernel identifier-terminal |
| 0xE1 | Combination | TLV string | |
|
Contactless combination for a given {AID - Kernel ID - Transaction Type} triplet |
| 0xE2 | Selected candidate combination | TLV string | |
|
Contactless combination sent by emtry point during kernel activiation |
| 0xE4 | FCI | TLV string | |
|
Selected canddiate's final select response |
| 0xE5 | Transaction related data | TLV string | |
|
Data used to trigger a transaction during start A |
| 0xEB | Kernel Resume Data | TLV string | |
|
If supported by a kernel, data used to perform a start D after an issuer online response |
| 0x9F06 | Matching AID | TLV | |
|
Selected candidate's AID |
| 0x9F0A | ASPRD | TLV | |
|
Not support yet |
| 0x9F29 | Extended selection | TLV | |
|
If exetended selection supported, AID post-fix |
| 0x9F3E | Terminal categories supported list | TLV | |
|
Not support yet |
| 0x9F3F | Selection data object list | TLV | |
|
Not support yet |
| 0x9F66 | TTQ | TLV | |
|
Selected candidate's TTQ |
| 0xBF0C | FCI issuer data | TLV string | |
|
Selected candidate's FCI issuer data |
| 0xDFA021 | Signal mode | Enum{C2=0, Other=1} | |
|
Signal management is not normalized between kernel specifications. Some cases such as Application Not Allowed or Empty Candidate List require to know in which mode the entry point shall formats output signal. Default value: C2 |
| 0xDFA025 | Reference transaction type | Byte value mirroing EMV tag 0x9C | |
|
Shall be defined before adding the first combination to filter combinations corresponding to actual transaction type |
| 0xDFA00A | Entry point pre-procesing indicators | TLV | |
|
Selected candidate's pre-processing indicators |
| 0xDFA00B | Autorun support | Boolean | |
|
Starting condition for entry point, i.e. how a transaction is initiated |
| 0xDFA00C | Skip polling | Boolean | |
|
Skip polling during start B |
| 0xDFA011 | ASPRD support | Boolean | |
|
Support application selection registered proprietary tag 0x9F0A |
| 0xDFA013 | TIDAS support | Boolean | |
|
Support terminal information during application selection tag 9F3E and 9F3F |
| 0xDFA039 | Kernel C-8 support | Boolean | |
|
Entry point supports kernel C8 |
Functional services
| Entry Point Service (see entry_point.h) | Description |
|---|---|
| EMVCO_ENTRY_POINT_SERVICE_START_A | Implements EMVCo start A. |
| EMVCO_ENTRY_POINT_SERVICE_START_B | Implements EMVCo start B. |
| EMVCO_ENTRY_POINT_SERVICE_START_C | Implements EMVCo start C. |
| EMVCO_ENTRY_POINT_SERVICE_START_D | Implements EMVCo start D. |
Card Processing Application (CPA) Service
Data model
Functional services
A CPA is a kernel that implements EMVCo's or payment networks' specifications.
| CPA Service (see cpa_name.h) | Description |
|---|---|
CPA_NAME_SERVICE_ACTIVATE |
activate a kernel as per EMVCo definition. |
Logger
Data model
Functional services
Implementation Conformance Statements (ICS)
All ICS presented in this section are a snapshot of moka capabilities. Kernels are always on maintainance and adapted to new needs and specifications versions.
Notation is as followed:
: supported
: not supported
: configurable
Mastercard
Implementation: EMVCo Contactless Book C-2, Kernel 2 Spec v2.11 
Profile = moka COTS |
Option |
|---|---|
| Mastercard CL Selection | |
| Magstripe | |
| SPI | |
| DE/DS | |
Visa
Release date: Q2 2025 
American Express
Implementation: Expresspay Terminal Technical Specification v4.2
Profile = moka COTS |
Option |
|---|---|
| ATM | |
| CASH | |
| CASHBACK | |
| CDA | |
| CDA Fail Detected Prior TAA1 | |
| Check Connection | |
| Delayed Authorization | |
| Exception File | |
| Goods Or Services | |
| Key Revocation | |
| Membership Data | |
| Mobille CVM | |
| No CVM Check Exempt | |
| Offline Only | |
| Online Only | |
| Online PIN | |
| Other Interface | |
| SDA | |
| Signature | |
| Status Check | |
| TVR Display After GenAc | |
| Unable To Go Online | |
| Zero Amount | |
| Attended | |
| All Mode | |
| EMV | |
| EMV Mobile | |
| MPOS | |
| Expresspay | |
| C4 | |
Profile = moka PCI-PTS |
Option |
|---|---|
| ATM | |
| CASH | |
| CASHBACK | |
| CDA | |
| CDA Fail Detected Prior TAA1 | |
| Check Connection | |
| Delayed Authorization | |
| Exception File | |
| Goods Or Services | |
| Key Revocation | |
| Membership Data | |
| Mobille CVM | |
| No CVM Check Exempt | |
| Offline Only | |
| Online Only | |
| Online PIN | |
| Other Interface | |
| SDA | |
| Signature | |
| Status Check | |
| TVR Display After GenAc | |
| Unable To Go Online | |
| Zero Amount | |
| Attended | |
| All Mode | |
| EMV | |
| EMV Mobile | |
| MPOS | |
| Expresspay | |
| C4 | |
Discover
Release date: Q2 2025