Skip to content

Getting Started

The sequence to follow to start working on an EMV project with switstack moka depends on the type of project to be implemented. But whatever the project, it is recommended to take a look at 2 important resources:

You can also visit this section to know which kernels are currently supported: see ICS.

These 3 sections present the context and the hypothesis required to understand what is switstack moka and how it fits in an in-store payment ecosystem.

EMV Acceptance

The term of 'EMV acceptance' covers all systems hosted by acquirers and merchants to enable card-present transactions. Switstack moka is a system that implements a series of EMVCo's and payment networks' specifications (see next section). It is usally deployed on a terminal. All these specifications document how a terminal shall process cards from different payment brands (Mastercard, Visa, etc...). That kind of system is subject to many certifcations to guaranty interoperability accross the world. Interoperability is the ability of an EMV acceptance system that is certified by different payment brands to accept any cards from these brands, anywhere it is deployed. That's the core of the EMV promise. And this is probably how EMV differentiates from any other payment means, i.e. on its ability to offer a secure worldwide acceptance.

References

So, switstack moka is a system part of the acceptance domain that implements contact and contactless specifications. In order to get an overview on the EMV standard, take a look at the following references (see EMVCo):

  • For EMV contact:

    1. EMVCo Book 1: card's structure and application selection;
    2. EMVCo Book 2: security and key management;
    3. EMVCo Book 3: core specification (recommended to start with this one);
    4. EMVCo Book 4: EMV ecosystem beyond Level 2;

  • For EMV contactless:

    1. EMVCo Book A: architecture and general requirements;
    2. EMVCo Book B: entry point specicfication;
    3. EMVCo Book C-2: Mastercard specification;
    4. EMVCo Book C-3: Visa specification;
    5. EMVCo Book C-4: American Express specification;
    6. EMVCo Book C-5: JCB specification;
    7. EMVCo Book C-6: Discover specification;
    8. EMVCo Book C-7: CUP specification;
    9. EMVCo Book D: communication protocol specification;

Additional specifications documents are used for regional kernels (debit networks).

EMV Level 2 characterization

EMV Level 2 solutions needs to be characterized because they are not functionally equal. They don't deliver the same set of features to acquirers and merchants. Consequently, they are certified for different purposes. Some are online only, others may be online with offline capabalities. Some delivers cash, others perform purchase transactions... The tool used to characterized them is called an Implementation Conformance Statements (ICS). Each payment network proposes different options. Along with the terminal's physical characteristics, an ICS defines terminal's functionalities.

Switstack moka adoption lies on a good understanding of business requirements. Please refer to ICS to make sure that the product is in line with your needs.

Note: there is a huge number of ICS combinations. Contact us to talk about your needs - if not addressed yet - and switstack's roadmap.

Terminal characterization

Any terminal, a.k.a device or hardware platform, meant to accept EMV cards embeds an EMV Level 2 stack to comply with payment networks' requirements. The combination of [Terminal x ICS] will determine which and how transactions can be peformed. Let's call it the EMV point of acceptance.

Starting an EMV project consists in identifying which type(s) of merchant will be served. The EMV points of acceptance typology could be presented as followed:

  • PCI-PTS points of acceptance

    1. Attended: online only/offline with online capability/offline only
      1. Magstripe: yes/no
      2. Contact: yes/no
      3. Contactless: yes/no
    2. Unattended: online/offline with online capability/offline only
      1. Magstripe: yes/no
      2. Contact: yes/no
      3. Contactless: yes/no

  • COTS points of acceptance (contactless only)

    1. Attended: online only
    2. Unattended: doen't exit (yet?)

Switstack moka serves any typology listed above. Configurations crossed with compilation options allows to address different business requirements. Whatever the typology chosen: - The process to integrate switstack moka on a new hardware platform is the same. - The process to qualify switstack moka with test automation is the same (moludo the test plan that depends on ICS). - The process to certify switstack moka with accredited is the same (moludo the test plan that depends on ICS).

Playing with the code

Switstack moka is an abstract EMV Level 2 stack that can run almost anywhere. It is convenient for demo, development, complex architectures, ... In parallel to the business analysis, playing with the code on a PC-based system is probably the best way to prepare the project and apprehend switstack moka:

  1. Get the code;
  2. Compile it;
  3. Perform transactions;

There are 2 modes available to perform transactions: - You may use moka in a virtual mode requiring virtual cards. This is the mode that is used to automate EMV tests and to emulate accredited testing tools. - You may use moka in a PCSC mode requiring actual cards. This is the mode that was used to qualify the stack against the different test plans implemented for certification sessions.

Get the code

Contact switstack to open a github account (see switstack). See repository's md file to get installation information.

Compile the code (virtual mode)

This mode can be used to replay transactions based on APDU logs.

Steps Description Command
#1 Clone the repository. git clone repository_reference
#2 Make the build for virtual mode. cmake -B build -S . -D CMAKE_BUILD_TYPE=Debug -D CMAKE_TOOLCHAIN_FILE=./external/cmake-toolchains/cmake/toolchains/gcc_linux-x86_64.toolchain.cmake -D MOKA_BUILD_TESTS=ON -D MOKA_BUILD_TEST_APP=ON -D MOKA_TRACE_CERTIF=ON -D MOKA_HAL=VEP-L -DSWITSTACK_VERSION="1.0.0"
#3 Compile the code. cmake --build ./build

Compile the code (PCSC-based mode)

This mode can be used for qualification with accredited tools, or with actual card.

Steps Description Command
#1 Clone the repository. git clone repository_reference
#2 Make the build for PCSC mode. cmake -B build -S . -D CMAKE_BUILD_TYPE=Debug -D CMAKE_TOOLCHAIN_FILE=./external/cmake-toolchains/cmake/toolchains/gcc_linux-x86_64.toolchain.cmake -D MOKA_BUILD_TESTS=ON -D MOKA_BUILD_TEST_APP=ON -D MOKA_TRACE_CERTIF=ON -D MOKA_HAL=PCSC -DSWITSTACK_VERSION="1.0.0" -DMOKA_MASTERCARD_MAGSTRIPE=OFF
#3 Compile the code. cmake --build ./build

Perform transaction

See Switstack moka Terminal.

  • Example of a command line in virtual mode 

    ./output/build/debug/apps/moka/moka -f /discover/dpas_conf14.txt -k discover.txt -t trd_00_xxx_00.txt -c /nfc/card1.txt

  • Example of a command line in PCSC-based mode 

    ./output/build/debug/apps/moka/moka -f /discover/dpas_conf14.txt -k discover.txt -t trd_00_xxx_00.txt

Warning

If you want to replay a transaction, set following TRD tags as followed: 9f 37 04 xx xx xx xx aligned on your transction to replay 9a 03 xx xx xx aligned on your transaction to replay

Warning

Actual cards coming from production use specific certificates that are not provided by switstack.

  • Example of a debug snapshot

Switstack moka debug

Using switstack moka in your project

Once you have a good understanding of what switstack moka is, how it works, and what its boundaries are, you can start architeturing your solution based on your business requirements.

There are different paths to work with switstack moka: 1. You are developing a COTS system and want to leverage on existing Letters of Compliance (LoC); 2. You are developing a PCI-PTS or COTS system and you want to port switstack moka;

Leveraging existing LoC

In the context of COTS projects, it is possible to own EMV Level 2 stacks that have been certified by a provider. You integrate a SDK along with the kernels of your choice (Mastercard, Visa, Amex, Discover, etc...). You build your payment solution without the need to perform any EMV Level 2 certifications. The benefits to use switstack moka are:

Benefits Included Description
Code Availability ⚫ The license includes an access to the code repository (see terms and conditions)
Test Automation ⚪ EMV Level 2 qualifications against official test plans are fully automated and may be integrated into CI/CD pilelines. This requires a specific service subscription (swittest)
Compliance ⚫ The license includes LoC and MPoC accreditation (see terms and conditions)
Maintenance ⚪ Specifications and test plans updates may lead to the modification of the stack. Systematic updates require a specific service subscription
Unified API ⚫ COST and PCI-PTS system running moka expose the same EMV Level 2 API to be integrated by payment applications

Porting switstack moka

You may want to take full control of the EMV Level 2 stack, and be granted with your own EMV Level 2 certificates.

If you are running a COTS project, this is achieved with minimum efforts because the EMV Level 2 has already been certified by switstack: 1. Get the code from switstack repository; 2. Target your COTS device using your parameters (kernels and ICS); 3. Qualify the stack; 4. Certify the stack at the lab of your choice;

If you are running a PCI-PTS project, you have to port the stack onto a new hardware platform. Before being able to run it on your device, it is required to adapt low level calls to the API services exposed by your firmware. It means that all the HAL layer must be overwriten so existing implementations (PCSC, and virtual cards) will be replaced with actual platform calls to support: - card polling - apdu exchanges - random number generation - crypto routines such as rsa, sha, ... - led displays - message displays - bip

It is a straight forward task.