Introduction
OLA stands for Open L2 API. It is a programmable interface normalize card processing (L2) services required by a payment application (L3).
Important: this interface has been desgined from a Nexo Fast perspective. OLA is a global initiative aiming to cover a missing key element in the payment ecosystem: the EMV L2 API. However, OLA is generic enough to support any kind of payment dynamic. beyond Nexo implementation
Principles
Interacting with a L2 stack is based a simple principles:
Set pre-conditions
Initiate transaction
Eventuall, complete transaction
Get post-conditions
There are different interfaces defined to support that sequence.
Hypothesis: a payment application (L3) controls the polling of the technologies, implements a specific region EMV application .selection mechanism (if needed), and owns the configuration (fetched from its TMS). Card processing (L2) is global, and only depends on an ICS that is aligned on merchant’s requirements. Consequently:
A payment application detects whether a contact or contactless application will be triggerred
A payment application implements the logic to select a final application based on OLA services
A payment application configures the EMV parameters based on the final selection
Interfaces
Interface | Description |
---|---|
ola.h | This interface presents different administrative services |
ola_emv.h | This interface presents common services required to support contact and contactless card processing |
ola_publickey.h | This interface allows a payment application to intialize a L2 stack with a set of public keys required to execute an EMV transaction flow (contact and contactless) |
ola_contact.h | This interface is meant to support contact transaction flow |
ola_contactless.h | This interface is meant to support contactless transaction flow |
ola_tags_dictionary.h | This header lists all the tags that are specific to Nexo Fast and consequently subject to a translation for further indexation in the L2 stack |
API
ola.h
#ifndef _OLA_H_ #define _OLA_H_ #ifdef __cplusplus extern "C" { #endif //--------------------------------------------------------- // Includes //--------------------------------------------------------- #include "ola_tags_dictionary.h" /// Generic Public Key configuration API #include "ola_emv.h" /// Generic EMV API #include "ola_publickey.h" /// Generic Public Key configuration API #include "ola_contactless.h" /// Generic Contacless Processing API #include "ola_contact.h" /// Generic Contact Processing API //--------------------------------------------------------- // Definitions //--------------------------------------------------------- typedef void (*logf_function)(char* str); //--------------------------------------------------------- // Primitives //--------------------------------------------------------- /// Version of the OLA API /// No compatiblity guarantees are made between different versions #define OLA_API_VERSION "2.1.1" /** * @brief Get the current version of the OLA Api * @return Pointer to a string representation of the API version */ const char *ola_get_api_version(void); /** * @brief Get the current version of the OLA Implementation * @return Pointer to a string representation of the API implementation */ const char *ola_get_implementation_version(void); /** * @brief Initialize OLA implementation. Need to include xxx_ola_adapter.h to interface to proprietary_data's type * @return OLA error */ tOLAError ola_initialize_implementation(const uint8_t *tlv, uint16_t tlvLength); /** * @brief Set a trace function */ void ola_set_trace_function(logf_function fct); #ifdef __cplusplus } #endif #endif
ola_emv.h
// NAME....... ola_emv.h // PURPOSE.... Level 2 Abstraction Layer for EMV primitives // to be used by the external world (Level 3 application) // PROJECT.... Arkos Payment Solution // REFERENCES. -- // // // Copyright 2005-2019 - 9164-4187 QUEBEC INC (AMADIS), All Rights Reserved // #ifndef OLA_EMV_H #define OLA_EMV_H //--------------------------------------------------------- // Includes //--------------------------------------------------------- #include <stdint.h> //--------------------------------------------------------- // Definitions //--------------------------------------------------------- typedef enum { OLA_OK, OLA_CARD_MUTE, OLA_CARD_BLOCKED, OLA_MAX_REACHED, OLA_NO_CANDIDATE, OLA_CONTACT_NEW_SELECTION, OLA_CONTACT_SELECTION_ERROR, OLA_CONDITIONS_NOT_SATISFIED, OLA_ACCEPTED, OLA_NOT_ACCEPTED, OLA_OFFLINE_ACCEPTED, OLA_OFFLINE_DECLINED, OLA_GO_ONLINE, OLA_DECLINED, OLA_MISSING_DATA, OLA_PINPAD_ERROR, OLA_PARAM_ERROR, OLA_NOT_IMPLEMENTED, OLA_ERROR, OLA_CARD_ERROR, OLA_CANCEL, OLA_PUBLIC_KEY_OK, OLA_PUBLIC_KEY_MISSING, OLA_PUBLIC_KEY_MAX_REACHED, OLA_PUBLIC_KEY_END, OLA_PUBLIC_KEY_NOT_IMPLEMENTED, OLA_PUBLIC_KEY_ERROR } tOLAError; //--------------------------------------------------------- // Primitives //--------------------------------------------------------- // Set a tag in L2 stack // Input parameter: // tag // value // length // Return // OLA_EMV_OK // OLA_EMV_PARAM_ERROR tOLAError ola_emv_set_tag( uint32_t tag, uint8_t *value, uint16_t length ); // Get a tag from L2 stack // Input parameter: // tag // Output parameter: // value : buffer to copy the value of the tag // length : the length of the value // Return // OLA_EMV_OK // OLA_EMV_MISSING_DATA: the tag is not present // OLA_EMV_PARAM_ERROR tOLAError ola_emv_get_tag( uint32_t tag, uint8_t *value, uint16_t *length ); #endif /* OLA_EMV_H */