Table of Contents |
---|
This section aims to support development teams to plan, to port, to integrate, and to certify Agnos Framework onto any payment platforms and infrastructures. It has been written from the experience of past porting projects from open platforms such as Linux PC to very constrained embedded environments using chipsets with limited processing and memory capacities (e.g. Cortex M3 with FreeRTOS). This guide also takes into account the different processor/acquirer projects in order to raise specific concerns to L3/L2 integration.
This document is organized to cover all the steps of the Agnos Framework integration. It’s about sharing different experiences allowing readers to go straight to the point and to anticipate on typical L2 and L3 challenges and constraints. However, the topic is so wide that it can’t provide all the answers for each specific environment. Still, a lot of questions are raised to structure the inception of modern card acceptance system and to help the management of L2 and L3 certifications.
Agnos Framework Porting Project presents the challenges related to Agnos certifications on new platforms and infrastructures with an accent on the methodology
Acceptance Project Scoping defines the limits of certification from 3 perspectives: L1, L2, and L3. It also provides information related to ICS
Architecture synchronizes the developer on physical and logical concepts to help identify the context of the Agnos Framework integration
Integrationdescribes how ACE – Amadis’ SDK – can be used to submit an acceptance system to L2 certifications
Specializationlists the GPI primitives that need to be overloaded
Important: L3 merchant, acquirer, processor specific implementations (or specific payment applications) and underlying certifications are beyond the scope of that document. Agnos Framework package addresses L2 needs (contact and contactless) and related L2 TA testing. Additional work needs to be performed to prepare L3 activities which depend on non-standard contexts (regional rules, specific acquirer/processor protocols, regional security schemes, merchant integration requirements, added-value applications such as loyalty programs, etc…). However, some references to L3 are made in that document to help developers to contextualize their L2 porting project.
Porting Project
Porting Agnos Framework to a specific platform is a kind of double challenge:
The first step is about kernels certifications when the system needs to comply with specific requirements and to pass different test plans in a laboratory context (L2 certifications). Examples:
EMVCo L2 certification
MasterCard PayPass certification
Book C-1 certification
…
The second step is about kernel integration certifications when the system needs to comply with specific requirements and to pass different test plans in a processor/acquirer context (L3 certifications). Examples:
...
Important: Specifications, and test plans change during the year. It’s important to know TA sunset dates to avoid project delays.
Path to L2 certification
L2 certifications are complex tasks. The complexity lies on:
...
Hence, there are 3 risks that must be mitigated during this stage:
⇒ Functional compliancy: running all the tests in the same conditions like during an official TA is the best way to mitigate that risk. However, a full TA qualification requires time and budget:
Test Plan | Manual Qualification Duration | Automated Qualification |
---|---|---|
EMVCo Contact | 10 days (1 baseline configuration) | N/A |
MasterCard PayPass C-2 | 12 days | TEI Available |
Visa payWave C-3 | 20 days (no DRL set) | |
JCB J/Speedy C-5 | 7 days | |
ART Available - No VCTKS | ||
American Express ExpressPay C-4 | 5 20 days (no DRL set)) | N/A |
JCB J/Speedy C-5 | 7 days | N/A |
Discover D-PAS C-6 | 5 days | N/A |
CUP QuickPass Overseas C-7 | 5 days | N/A |
Interac Flash | 5 days | N/A |
Eftpos | 7 days | N/A |
PURE | 5 days | N/A |
⇒ Performance compliancy: booking early debug slots and performing the exact same tests as for a TA is the only means to mitigate that risk. These tests called performance, combination, and cross testing use special equipment and special cards/mobile phones. That step may be anticipated as soon as the GPI and basic functional tests have been performed on the device. In average, this time is around T0 + 10 weeks of work
⇒Timing: specifications and test plans change – independently - during the year. It’s important to plan which versions are targeted (specifications and test plans) based a specifications and test plans sunset dates
Path to L3 certification
L3 certifications are lighter than L2 certifications (in term of number of test cases) but very contextual preventing to document a full standardized guide. L3 depends on “kernel” certifications that are granted by labs and/or payment networks but also on the acquirer/processor environments that are targeted for the end-to-end integration. The purpose of this document is not to cover that stage. However, it’s important to know that L3 tasks shall be anticipated way before L2 activities and LoA issuances.
...
Processor/acquirer protocol
Processor/acquirer data model
Batch or data capture management
Exception file list management
Key revocation process
Transaction flow and user experience
Security scheme like online pin block generation
EMV application in the US and in Canada
Dual polling (contact/contactless)
Split sales detection
Loyalty program integration
Transportation program integration
Gratuity capture
…
Process
This diagram below represents an example on how a porting project may be sequenced and paralleled:
...
The kickoff is used to share all the project constraints. It is not dedicated to planning activity which is a separated task that needs to be performed during project management working session. It’s a good time to parse the contract and the agreements to make sure that deliverables and milestones are well understood
During a face-to-face meeting, the training is used to learn Agnos API, and to emulate a project execution. For example, the parallelization of L2/L3 activities is an important topic that is covered. Training may be skipped depending on team’s skill and experience on the topic
Planning is essentially an activity depending on customer’s time to market constraints. Amadis is involved to advice on TA preparation times, and on specific Amadis resources availability. But Amadis hasn’t the responsibility to define and to maintain the schedule (there is one exception: if Amadis submits TA on its name)
Before starting development activities, it is important to commit on product and architecture definitions because subsequent tasks are directly impacted. Development team integrating the GPI needs to get a document (High Level Requirements) explaining the project including: Business requirements, Planning, Logical and physical architectures, Platform characterization
Milestones
Each project comes up with its own constraints. However, porting Agnos Framework to a new platform is a pretty standard process crossing always the same milestones which can’t be avoided.
Milestone | Comment |
---|---|
High Level Requirements | Definition of the project |
Planning Definition | Prerequisite: High Level Requirements |
ICS Forms | Prerequisite: High Level Requirements |
GPI Integration | Prerequisite: High Level Requirements |
Agnos Qualification | Prerequisite: GPI Integration and ICS Forms |
Certification Packaging | Prerequisite: Agnos Qualification |
Agnos Certification | Prerequisite: Certification Packaging |
Acceptance Project Scoping
An implementation project for an acceptance system may be split up into 6 distinct domains in order to scope what has to be delivered:
...
Platform, the low level of the acceptance system’s architecture supporting all services required to get EMV kernel certifications
Agnos, the corner stone of the EMV acceptance system to be ported (alias the framework)
L3 and its interface, a.k.a. PoI or PoP, driving the framework and interfacing with 3 external systems: Processing(providing an interface to route financial messages), TMS(providing an interface to manage configurations), and Acquirer Security (defining security rules to integrate in order to accept transaction in the acquiring infrastructure).
There are 2 others domains in relation with L3 (outside the payment system):
Sales, using the L3 interface available in order to trigger transactions
KeyLoading, implemented as a Acquirer Security interface available for Key Loading System in order to initialize the acceptance system with secure artifacts required by the acquirer security scheme
...
Note: L2 LoAs granted during kernels certifications stages will be used as inputs to perform L3 Integration certifications stages.
L1 Characterization
In the scope of this Wiki, L1 domain covers all platform related services. Hypothesis:
...
Here is a list of example topics to be addressed during that stage:
⇒ [PDC1] Is there an Operating System?
No
There is no File System: to realize a data configuration files access layer in GPI that is dependent on flash memory management. It’s important to raise limitation as soon as possible (like maximum size of memory data segments, size required to store configuration data sets, strings table, …
There is no Dynamic Library Loading mechanism : to use payment application static loading mechanism (_STATIC_LOADER_ and _STATIC_LINK_ options)
...
Android: Do you need a Java to NDK API?
Linux
WinCE
Proprietary
⇒ [PDC2] What is the memory size available?
Flash? In Kbytes
RAM? In Kbytes. That size is very important. It may limit the number of simultaneous kernels
⇒[PDC3] What are the communication interfaces available? Data exchange size limitation?
Ethernet
Ethernet over USB
Serial USB
Serial Bluetooth
Other
⇒ [PDC4] Is there any consummation constraints?
⇒ [PDC5] Is there a keyboard?
No
In contactless, there will be no hardware pin-pad to pass ONLINE PIN / STOP BUTTON test cases in PayPass (not ICS options)  to use ACE to simulate pin entry and stop
Fill CT/CL ICS accordingly to avoid extra works limitation UI emulation;
...
Make a particular attention to bouncing and performance impact on keyboard scanning
⇒ [PDC6] Is there a display?
No
What are the regional rules related to display-less devices?
⇒ [PDC7] What are the card interfaces available?
Magstripe
Contact
Contactless
⇒ [PDC8] Does the chipset include a L1 certified contact stack?
No (when, in regards with GPI integration timings)
⇒ [PDC9] Does the chipset include a digital L1 ready-to-be-used contactless stack?
No (when, in regards with GPI integration timings)
⇒ [PDC10] To what extent is the platform consistent with L3 security requirements?
PCI compliancy
End-to-end encryption
Master/Session or DUKPT
Key loading mechanisms
Boot loading
Track’s service code availability?
L2 Characterization
In the scope of this Wiki, L2 domain covers Agnos Framework components independent from the platform and implementing L2 rules. This activity is about ICS definition.
Contact ICS
That step consists in defining what are the mandatory features that a contact L2 library needs to provide to L3 payment application so that business requirements will be supported in the field.
...
Go to http://www.emvco.com to get very last ICS forms, administrative process description, bulletins, etc…
[ICS_K1] Which EMV features are supported?
Unordered List ItemRefer to Agnos ICS references to define your ICS
[ICS_K2] Which EMV features are minor?
Use minor criteria to have a lighter ICS in term of number of features. Minor features may be added/removed without recertifying during L3 TA setup
[ICS_K3] Do you need several ICS?
Use a baseline and several increments to avoid recertifying from scratch a subsequent ICS
[ICS_K4] Is there an appropriate time to certify a CT
Note that every year, there is an EMVCo specifications or/and test plan update. Please contact a lab for more information
Contactless ICS
For contactless, the paradigm is pretty much the same as for contact: defining an ICS is mandatory to extract the list of test cases that will be used to run the TA sessions and get the LoA. The major difference lies on the fact that there is no standard ICS across the brands. So, one different ICS has to be filled up for each CL kernel. As a pre-requisite to these tasks, it requires a license from the payment networks releasing kernel’s specifications to be certified.
[ICS_CL1] Where is the antenna’s center?
A logo needs to be displayed right at the center for TA session
It’s important to avoid logo blinking during transaction flow while display messaging occurs
[ICS_CL2] How will time frames be measured?
Beeps or LED may be used. Use beep for better results
[ICS_CL3] Is there a keypad?
Yes
Online PIN supported?
Transaction cancellation?
...
A virtual keypad in ACE may be used with MasterCard PayPass (for online pin, and stop button), AMEX ExpressPay (for online pin)
[ICS_CL4] Is there a display?
Yes
There are no EMVCo requirements related to UI. Only recommendations
At least, 2 lines are required. Do not forget the logo
[ICS_CL5] Is the polling timeout configurable?
[ICS_CL6] Is their a chip interface?
You may refer to Agnos Framework Functional References Sheets to define your ICS (provided on demand).
L3 Characterization
In the scope of this Wiki, L3 domain covers all software component outside Agnos Framework and GPI scopes. Hence, this domain is not part of Agnos kernels certifications targeted during the portage project. Below, a short summary is provided to contextualize the different topics to be addressed once/while Agnos has/is been/being ported and certified.
Payment, Processing, and Configuration
Out of the scope.
That topic refers to the 3 main interfaces that a PoP needs to integrate for an appropriate design:
TMS interface, i.e. how to configure the PoP
Sales to Payment interface, i.e. how to trig a payment
Processing interface, i.e. how to interface with a payment host
Interfaces to Sales Domain
Out of the scope.
That topic is crucial to develop a stable payment system across the time. It’s important to study that coupling level to avoid re certifications and PCI exposures.
Interfaces to Acquirer Secuiry Domain
Out of the scope.
That topic is dependent on the security scheme that will be used to integrate Agnos. L3 may require specific keys to be uploaded to support Master/Session or DUKPT mechanisms. The acquirer’s security scheme is used to support online block PIN, messages MACing, data integrity during data exchanges with host, or end to end encryption when available.
Architecture
Logical Architecture
The logical architecture is independent from the physical constraints. Agnos Framework doesn't make any hypothesis on the deployment model that will be used. See Logical Architecture - Contact Project and Logical Architecture - Dual Project.
Physical Architecture
Defining the physical architecture is about defining which Agnos Framework components run of the host/acceptance device.
⇒All components run on the acceptance device
No
API serialization is required
⇒ Some components run on the acceptance device, and some on the host. At which abstraction layer of the logical architecture is the physical separation?
GPI: only the GPI API needs to be serialized
Agnos: Agnos plus GPI APIs need to be serialized (contact only project)
Entry Point: AgnosEP plus AgnosMW plus Agnos plus GPI need to be serialized (contactless project or contact + contactless projects)
L2 Certification
In order to prepare the system to a certification once integrated, here are 2 important topics to address at the beginning of the project:
⇒ [CERT1] Do you have an SDK (test environment) to certify the system?
No
ACE is available, where does the testing Level3 run?
On the host: API serialization is required
On the device: ACE serialization is required (use ACE2PAdapter)
Yes
Use ACE2P protocol documentation.
⇒ [CERT2] What is the communication link between ACE and the device?
IP
...
Use ACE2PAdapter and ACE2PPOP as delivered (provided on demand)
Use direct TCP/IP (recompile DualCertificationLevel3, ACE2P, SPED without the symbol _ADAPTER_)
Not IP
...
Use ACE2PAdapter as delivered and implement a specific ACE2PPOPUse Windows Serial