Back to Engineering Blog

An "Integration-First" Approach to Building a Commerce Platform for Payment Terminals

May 14, 2018

Commerce today doesn’t just happen online or offline, but through every possible medium. Mobile Commerce, Voice Commerce, and Conversational Commerce, amongst others, are a few example of what is generally referred to as Omni-Channel Commerce. And with the recent innovations like IoT, how various physical systems and processes interact with each other is totally different from the traditional ways of connecting things. This evolution of technology and interactions across physical and virtual systems, customer shopping behaviors and the ability to build omni-channel experiences requires a different approach than just building APIs. Systems and Components on the Commerce platform need to be designed and built for interconnectivity, interoperability and extensibility, thereby allowing developers to build new shopping experiences. This is what we call as the "Integration-First" approach. In this post, we will go through how we’ve built such a Commerce Platform at Poynt.

Where did it all start?

Before we jump into the details of an "Integration first" approach, let’s go over the essential components of a Payment Terminal and what kind of role they play. Traditionally Payment Terminals are mostly used for processing a card based (credit/debit) payment transaction. They typically consists of:

  • Card Reader - the core component of a terminal that provides all the physical and logical interfaces to read payment cards (Magnetic Swipe, Chip and NFC).
  • Display - to display prompts for customer/merchant to input data (like amount to be charged or asking customer to enter pin or payment type).
  • External hardware interfaces - provides connectivity in/out through various physical (RJ11/Serial/USB) and network interfaces (Ethernet/Wifi/Cellular). These external interfaces are the only way for the Payment Applications to authorize payments for the merchants and interact with an external accessory like a receipt printer or a POS system.
  • Printer - It is very common in most of the Payment Terminals to provide an inbuilt receipt printer for printing transaction receipts.
  • Keypad - a numeric keypad for secure input of PIN, amount and other details as needed to process a payment transaction.
  • Payment Application - software that brings everything together to allow a merchant to process a payment. It orchestrates the card reader, the display and other interfaces as per the payment processor/acquirer needs.

In addition to these on the terminal itself, most of the terminal vendors provide a few other services/features like:

  • Terminal/Estate Management - this provides a way to manage every terminal remotely for maintenance, software updates, technical support, etc.
  • Security Management - this provides a way to manage card reader configurations, encryption keys, etc.

Unfortunately, most of the terminals treat these as standalone components and provide low level access to the physical and logical components (almost at the device driver level in most cases). While this sounds very flexible for developers, being able to utilize these components in whichever way they want, it does bring the challenges with integrations, security and certifications.

Challenges with Integration

All Terminals come with an Operating System (also called "application controllers") with varying levels of programmability and access to the core features of terminal hardware. Typically they all provide an SDK for application developers to build their applications, which when done are submitted for certifications and approvals before they can be installed on real Payment Terminals at merchant locations.

Each application provides a distinct set of features and they are exposed to the merchant through the application controller interface on the terminal. Unfortunately there is little to almost no framework or interfaces provided to help these applications to collaborate with each other, resulting in a long list of completely stand alone applications. A good example of this is what we see when we visit a store, the merchant trying to select different button combinations to invoke different applications for different needs (eg. gift card vs credit card, credit vs debit, etc.).

Challenges with Security

The applications that are built for these platforms typically run inside the secure environment and thereby are required to meet all the security requirements of the PCI council, Card Networks and Acquiring banks.

Unfortunately, although these security requirements are essential for protecting sensitive consumer payment card information, they do come with a cost.

  1. Additional requirements that add to the development costs of payment applications
  2. Long testing and certification cycles, and
  3. The prolonged time to deploy significantly slows down the effectiveness of releasing new features and the lack of flexibility in software management severely impacts the software development cycle

Challenges with Certifications

As mentioned above, every payment terminal must go through a long list of certifications as needed by various regulatory and financial organizations before it can operate at a merchant store to process transactions. These include certifications which are typically called L1 certification (hardware and communication level for both Contact and Contactless), L2 certification (EMVCo for Contact and for each payment network for Contactless), and last but not least, another long certification cycle with every acquirer/processor the Payment Application running on the terminal integrates with. These certification processes require access to additional testing tools (which are quite expensive) to run and evaluate all test cases defined by the payment networks before submitting for the necessary approvals.

Building the Platform

With the challenges at hand and the goal to enable simpler integrations and integrated experiences, our approach has started with the breaking down of the hardware and software components into several abstraction layers, and exposing the functionality as APIs based on the integration needs.

A few core principles were established during this process:

  • APIs for every component on the Terminal ( an API-first approach) - this goes from rendering a custom UI message on the display, to processing a transaction through the processor.
  • Data and APIs extend beyond the terminal - available as simple RESTful external interfaces for any other system or application that needs them.
  • Interoperability both within apps and with external components is a must.
  • No 1:1 custom integrations between apps.
  • Security built in - not an option.
  • Ease of integration - no custom tools necessary; developers should be able to use the modern development and troubleshooting tools that are most commonly used.

Using these principles, the following core services were defined to abstract the functionality as appropriate:
Poynt Payment Terminal Integration

  • Card Reader Service - rather than providing access to low level card reader interfaces that would give access to sensitive card data to everyone, we added functional APIs to process card data as per the needs of the application. This includes performing a card transaction to process a payment, reading a non-payment card for loyalty and other use cases. All the data is encrypted inside the card reader services, thereby completely avoiding the exposure of any sensitive data to the applications and hence the need for any PCI compliance.
  • Commerce Services - provide the support for assorted commerce related functionality such as order management, transaction management, customer management, catalog/products, etc., and also a consistent representation of various commerce related data resources. These Commerce Services also become the core integration point for all applications running on the terminal to interoperate with each other serving various aspects of a commerce activity.
  • Payment Experiences - provide a standardized experience for all payment methods and removes the unnecessary burden of repeated payment certifications for every integration.
  • Accessory Management Service - provides a directory of various services that handle connectivity to external accessories (printers, scales, cash drawers, registers, POS systems, etc) attached to the Terminal and an easier way to interact with them. Various API Contracts are defined for different types of accessories. For example, a cash drawer accessory interface has simple "open()" and "isOpen()" methods rather than a low level USB command to send a specific raw byte value to open an attached drawer.
  • Capability Management Service - provide a directory of various capabilities installed on the platforms and the ability to connect and utilize those. The capabilities include transaction processing, receipt printing, loyalty, discounts, customer management, etc. Capability Management plays the most important role in the interoperability across various applications running on the terminal.
  • External Connector Service - provides an interface to expose most of the interfaces available on the Terminal to external applications connected over USB, BT or Network.
  • Cloud Services - provides necessary interfaces to extend the services on the terminal beyond the terminal itself. These services provide access to the same features, and more importantly, access to the same commerce data via cloud, providing an easier access to apps running in the cloud. The Cloud service also provide the necessary configuration management for various components like card reader, security key management, etc.

To illustrate how these components come together from an implementation and integration point of view we’ll examine an end-to-end Payment transaction flow on the Poynt Smart Terminal.

On the Terminal, every transaction begins from an application that the merchant is using to run their business. The following flow diagram walks you through various steps and phases of a payment transaction on the Poynt Smart Terminal. The callouts highlighted in red indicate functional APIs provided by the corresponding services.

Poynt Payment Terminal Interation


While that appears like a long process, a few important learnings that I would like to call out are:

  • Functional APIs - reduce the effort of integration tremendously through abstraction at a high level.
  • Service Discovery - being able to discover available services on the terminal adds the flexibility of finding an appropriate service that best suits the application needs. Whether it’s a service to send email, or a service to process a transaction, or a service to render a specific screen to collect data from the consumer - the ability to discover and connect programmatically not only adds a significant value to the application developers and but also provides a nice platform for extensibility.
  • Resource models - while the APIs for each component might differ in terms of the protocol formats based on the type of component/service it is, providing and maintaining consistent data models across them plays a very important role for interoperability.
    • This not only helps in passing the data across different APIs without requiring much transformations, but also helps in extending the data models as RESTful APIs for the applications running in the cloud.
  • Standardized API interfaces for Interoperability - while the Service Discovery provides a nice way to find the available services as and when needed, they add very little value when it comes to integration if their service interfaces are not standardized and predefined by the platform. Defining and providing the framework for standard interfaces for all possible Capabilities and Accessory services in the platform is a very necessary step for platform extensibility. There is no way we can predict the needs and features of every possible capability and accessory - so it’s very important to keep an open process for this to allow developers an ecosystem to help in defining these.

While the API-First approach is a necessary step at any company or product, focusing on how systems and applications (both internal and external) integrate and interoperate with each other is very essential for the success of any platform.

Key Takeaways

  • All payment terminals come with an Operating System (also called "application controllers") with varying levels of programmability and access to the core features of the terminal hardware.
  • The SDK provided for developers tends to be very low level, and developers typically have to manage integration, security, and certificates themselves.
  • The Poynt team took an Integration-first approach with RESTful APIs to external services.
  • The APIs help simplify integration and security, and provide a better developer experience making it easier for developers to meet specific needs or integrate a new accessory.

About the Author

Praveen Alavilli is a principal founding engineer at Poynt, laying the technology foundations for the Poynt Smart Terminal and its open commerce platform, and growing them to scale for the future of payments. Prior to joining Poynt, Alavilli was leading architecture and technology in the fields of payments, identity, authentication and security at various companies like PayPal, eBay, Amazon and AOL. Alavilli has long been a proponent of open standards, and open developer ecosystem.