Payment Pebble Mobile Application API 1. Introduction The purpose of the Payment Pebble Mobile application API is to allow third party integration of the Payment Pebble as payment processing device into mobile apps. This means that a third party having developed an app for their own services can accept card- present chip & pin transactions within that app using this API and the Payment Pebble. This document describes the high- level aspects of the API and some key elements of its structure. Currently the API is being developed for Android, ios and Windows Phone. 2. Why a Payment Pebble Mobile application API? Figure 1 With a Mobile app API, the market of Payment Pebble users expands dramatically One of the biggest advantages of the Payment Pebble is its enabling function. Merchants who could previously not accepts cards suddenly find themselves with an affordable, mobile, secure solution that opens up the opportunities of cashless transactions without delay. The Payment Pebble mobile app API creates a whole new type of merchant. Mobile app developers can now integrate secure card- present payments in their app, reaching into the physical world like never before. They become merchants. They can create products (apps) that extend existing merchants empowerment by enabling them to integrate this secure payment system with other business services. App developers can independently innovate and invent services that don t yet exist. The scenarios below are but a few examples of this capability. a. Branding A large delivery company decides to start accepting card- on- delivery payments and equips its delivery staff with Payment Pebbles. In order to ensure the customers trust in the new payment system, they decide to create a payment app branded with their logo and other identifiers, such as the name and a photo of the delivery person. Payment Pebble Mobile Application API thumbzup 2014 1
Figure 2 Branded delivery app with payment functionality b. Product and service management The network of emergency plumbers NowPipes has adopted the Payment Pebble because in many cases their customers call them out on an emergency and do not have the cash on them to pay the call- out fee or the repair. This leads to a tedious process of invoicing, follow- ups and EFT reconciliation that uses up valuable time and resources for the company. To improve this, they have developed an app that lists the services that are provided, each with a fixed price that is shown to the customer and is identical to the price list on their website. Customers confidence is increased; they don t feel exploited because they are in an emergency situation. The dispatched plumbers can only select the specific items and services from the app to build a clear invoice for the customer on the spot. The Payment Pebble mobile app API is used to process the payment. The invoice can then be emailed to the customer and head office with confirmation of payment and reference number for their bookkeeping. Figure 3 In- app product and service catalogue integrated with Payment Pebble card payments Payment Pebble Mobile Application API thumbzup 2014 2
c. Sales management Adams rent- a- bike allows people to book bike rentals on their website. This helps them manage their bicycle park. If they have more customers than bikes, they can even rent bikes from the competition and keep the new customers and their business to themselves. Adams have developed an app that retrieves bookings from their website on a smartphone and when the customers arrive, they can pay for the rental at the bike stall by card using the Payment Pebble. Payment and booking are instantly reconciled. Figure 4 Booking management app with payment capacity 3. Payment processing structure The way the Payment Pebble processes payments is compliant with the most stringent industry security requirements. A payment processed with the Payment Pebble and its app is a card- present transaction equivalent in every aspect to a transaction carried out on a traditional card terminal. The only two changes to a traditional customer experience are: - Electronic receipting via SMS or email, and - A slightly different PIN entry method. The Payment Pebble is EMV Level 1 & 2, and PCI compliant. The Payment Pebble is the only trusted element in the merchant s hands and the mobile device remains blind to any sensitive data. In terms of the mobile app, this translates into the following:! The app never sees any sensitive data. The Payment Pebble encrypts all data. The mobile device serves only as a communication pipe to send encrypted blobs of data to the bank and pass on the encrypted response from the bank back to the Payment Pebble. Figure 5 Roles of the app. The phone serves as communication platform for encrypted data exchanged between the Pebble and the backend (the bank). Payment Pebble Mobile Application API thumbzup 2014 3
! The Payment Pebble drives the flow. The app can only give the Payment Pebble what it asks for, e.g. a transaction amount. The app can never request anything from the Payment Pebble or make it do anything specific.! When the Payment Pebble requests input, it is the role of the app to get it from the merchant or the customer to the Pebble through the user interface, e.g. display a number field and a keypad to enter a transaction amount. This is where the app developer comes in.! In addition, the app or the phone/tablet never sees any PIN digits. a. Payment Flow Figure 6 illustrates the payment flow using the Payment Pebble. It shows the only functions of the app, i.e. requesting input from the merchant/customer, sending encrypted data to the backend and passing the encrypted response back to the Payment Pebble. This simplicity is reflected in the API. Figure 6 Payment Flow. See below for the PIN entry. Red arrows show encrypted data. Payment Pebble Mobile Application API thumbzup 2014 4
4. API structure a. Overview There are technically two interfaces from the phone; one to the Payment Pebble and one to the backend but the API is structured such that developers don t need to distinguish between the two. The interface details are simply defined before compilation in two specific files, the communications and backend modules. In addition and for security reasons, the Payment Pebble drives the flow, not the app. This, as well as exception handling, Payment Pebble initialisation and hardware- related functionalities (e.g. keeping the Payment Pebble awake, keeping an eye on the Payment Pebble battery charge level, etc.) are automated in the API and should any action be required, the developer can easily programme those as described below. This results in an API that is robust, convenient and easy to use. b. Modules Integrating Payment Pebble payment capability into a mobile app depends on a few parameters to be defined in modules before compilation. Those parameters define: - Backend details where transactions are processed (not the merchant s own backend) - Device details, for example whether compiling for a device or the Pebble emulator for testing. Behind this simplicity of use resides a powerful structure that is capable of handling all necessary processes and a vast array of exceptions. c. API Core Module The Core module handles all the Payment Pebble flows, including keeping it awake, Payment Pebble status management, handling exceptions, etc. Third party developers do not need to know any aspect of the internal workings of the Payment Pebble or the Payment Pebble flow. d. Pebble Data Flow This is not technically a module but an input to the Core module. The Payment Pebble will need data to act upon, such as transaction amount, type of card, etc. This data comes from the app through actions and controllers. The Payment Pebble requests those inputs in an order that is dictated by EMV. The Payment Pebble leading the flow therefore ensures compliance with those rules. e. Communications module One communications module needs to be included at compilation. If the app is to be complied for Android, the Android audio file should be included. Similarly for ios and Windows Phone. An app compiled with the Android audio module for example, will need a physical Pebble plugged into an Android phone to work. This is why a Pebble emulator communications module is included in all SDKs. f. Server module Similarly to the communications module, one server module needs to be included. Modules for testing and for deployment into production will be needed by developers. For ease of development, a backend emulator with some generic rules is available too. Payment Pebble Mobile Application API thumbzup 2014 5
5. Software Development Kits (SDKs) From the developer s point of view, only a handful of functions are needed to have a fully functional app being able to process payments securely using the Payment Pebble. What s more, default files describing supported host devices and backend servers as well as code examples are included in the API. Those elements are then combined into platform- specific SDKs. Packaged Android, ios and Windows Phone SDKs includes the core module, Payment Pebble and backend emulators, and the appropriate audio communications module. An app can be compiled with either the audio communications module, or the Pebble emulator. In the latter case, the app can be tested without needing a physical Pebble. 6. Conclusion Thumbzup has developed a mobile app API to use with the Payment Pebble. This API creates unprecedented opportunities for all parties in the 4- party model, as well as the creators of the new mobile app economy, app developers. This modular API incorporates all the inner workings (and exceptions) of the Payment Pebble and enables an app developer to integrate payment- processing capabilities within a mobile app with very little effort. It also guarantees the integrity of the Payment Pebble s security and compliance with security requirements of card- present transactions as required by EMV. v. 03 September 2014 Payment Pebble Mobile Application API thumbzup 2014 6