Payment Pebble Companion App API 1. Introduction The Payment Pebble Companion App API (hereafter Companion API) provides a simple means to integrate payment capabilities into a third- party mobile application. It allows a third party application to call the Payment Pebble application, hand over any necessary data that are required for a transaction, and receive back the results of handling the transaction from the Payment Pebble application. This requires the installation of both the third party app and the Payment Pebble app on the mobile device. Figure 1 Representation of the Payment Pebble Companion App API 1. A third party app sends a companion call to the Payment Pebble app with pre- populated payment details (amount, reference number, receipt recipient) 2. The Payment Pebble app processes the payment (requesting card and PIN from the customer according to its EMV- compliant app flow) 3. The result of the transaction is passed back to the third party app. Although not technically an API, it enables fast production and familiarisation with the payment flow. It can be used to get a payment capability into an existing app very quickly. In addition to the Payment Pebble Companion App API we provide a Payment Pebble Emulator to facilitate development without the need to already be in possession of a Payment Pebble. Advantages of using the Payment Pebble Companion App API: Security Mobility Affordability Card- present payment Integrated 2. Business value and use cases The business value of the Companion API lies in the ability of an existing business to integrate secure chip- and- pin or magnetic stripe- and- pin mobile card- present payments quickly and easily. It makes payment enablement for any third party system (ERP, POS, Accounting etc.) possible by provisioning a lightweight mobile client that can be installed on a mobile phone or tablet. The Companion API turns a Payment Pebble into a highly secure EMV card- present terminal for any external application. It also offers easy access to value added services like vouchers or prepaid Payment Pebble Companion App API thumbzup 2014 1
products with minimal development effort and requires no additional certification. With a few modifications to an existing application, payment can be incorporated into an existing app, allowing the business to take full advantage of its existing investment in mobile development. A merchant portal is also provided, which gives merchants overviews and insights into their business and offers many other functionalities, including cashing up staff at the end of shifts, mapping transactions or pre- configuring transactions. 2.1. Use case: the Acme Towing company The Acme Towing company has developed an app for its drivers to track their activity. Their app uses the Companion API to enable drivers to process card payments using the Payment Pebble. One of Acme's tow trucks was called out to a vehicle. On arrival, the tow truck driver collected all the owner's details, including any insurance information from the customer, using the Acme Towing app. The app estimated the towing distance using a mapping service, and the owner was provided with a quotation using the app. The owner accepted the quote. When the driver was ready to take payment, he clicked the Pay button in the Acme towing app. At this point control and payment data were passed to the Payment Pebble app via the Companion API. Figure 2 Payment in the Acme towing app using the Companion API The Payment Pebble app requested either a debit or credit card and the transaction was authenticated using the card- holder s PIN. The Payment Pebble app processed the transaction, including the sending of the receipt and sent the result back to the Acme towing app upon completion of the transaction. The remainder of the Acme towing app flow then proceeded. 2.2. Use Case: Expedited Delivery Company Expedited Delivery Company provides a food ordering and delivery service in urban areas throughout the country. They have a mobile app that their drivers use to collect orders and determine the location of the order delivery. They have had this app for some time, and it works very well for managing their drivers. However, the need to take cash has always been a gap for them. It exposes the drivers to risk, and it is difficult to track and manage. Existing payment solutions do not solve some of their challenges, especially the need for each driver to cash up at the end of a shift. Payment Pebble Companion App API thumbzup 2014 2
Expedited Delivery approached thumbzup regarding the potential to incorporate the Payment Pebble into their driver's workflow, and to have the payment integrated into their existing app. Figure 3 shows some of the screens involved in a transaction to illustrate the app flow. Working with thumbzup, Expedited Delivery also created a simple back- end portal that enabled certain management functions. One of the most important features that forms part of the management portal is the ability to cash up at the end of a shift (Figure 4). This enables the drivers to create a record of revenue received during a shift and ensure that any commission due is correctly allocated. Expedited deliver also use additional drivers when busy and in order to ensure the integrity of its services, it makes use of the preconfigured payment facility on the portal. Thus, casual drivers can only get paid for specific deliveries with the specifics of each transaction already recorded in the system. The portal is also able to display the location of the transaction, and where multiple transactions exist they may be grouped together on a map for display (Figure 5). This can be useful for planning purposes as a manager can see where orders/deliveries are clustered, and allocate more resources to areas where there is greater activity. This system not only added the capacity to accept card payment to Expedited Delivery Company business, it also added other rich reporting and management tools. Figure 3 Payment flow in an Expedited Delivery Company transaction, showing where the transaction is in the Expedited delivery app (blue border) and where it is in the Payment Pebble app (red border). 1. The transaction begins when the driver clicks new sale (top left). Payment Pebble Companion App API thumbzup 2014 3
2. The driver captures the details including the invoice number for the delivery and clicks the Pay now button. 3. This transfers the control to the Payment Pebble app, which then initiates the payment. 4. The Payment Pebble app asks for the card (not shown), and for the cardholder s PIN. 5. At the end of an approved transaction, removal of the card transfers control back to the Expedited Delivery app, along with the transaction results. 6. The Expedited Delivery app resumes. Figure 4 Expedited Delivery management portal Figure 5 Driver cash- ups Figure 6 Mapping transactions Payment Pebble Companion App API thumbzup 2014 4
Use Case: Wonder Clothing Stores Wonder Clothing Stores runs a nation- wide chain of medium- cost, good quality clothing stores. The stores are very popular, and are often crowded on weekends and at month- end. Store managers would like to ease congestion at the till during busy times. In addition, they often have stalls in the foyer and on the pavement outside the shop. They are looking for a way to take card payments in a mobile way, while connecting to existing point of sale systems. They decide to equip their stores with mobile devices. They create a mobile application that integrates into their POS system and allows staff to scan of barcodes for pricing and product information using the device camera. Once all items in a sale have been added, the sales staff can click Pay, at which point the Payment Pebble app takes over. This effectively turns their fleet of devices into a highly mobile card- present payment solution linked to their POS system. Figure 7 Payment flow in a Wonder Clothing transaction, showing where the transaction is in the Wonder Clothing app (blue border) and where it is in the Payment Pebble app (red border). 1. The transaction begins when the staff clicks Start Transaction 2. They scan all the items to be purchased, retrieving product information from their POS systems and click the Pay button. 3. This transfers the control to the Payment Pebble app, which then initiates the payment. 4. The Payment Pebble app asks for the card (not shown), and for the cardholder s PIN. 5. At the end of an approved transaction, removal of the card transfers control back to the Wonder Clothing app, along with the transaction results. 6. The Wonder Clothing app resumes. Payment Pebble Companion App API thumbzup 2014 5
2.3. Use Case: SpeedFast Couriers SpeedFast Couriers is a national, long- distance delivery service company that prides itself on being fast, efficient and affordable. Their route planning software, built on their custom- build ERP system, is part of their competitive advantage. They are seeking a card payment system that can integrate with their ERP and enable drivers to pick up routes and take payment on delivery. They choose to integrate the Payment Pebble into their systems through its companion API. The central dispatching office uses the ERP system to plan routes and to schedule deliveries. The deliveries for the day are scheduled per driver, and optimised using the SpeedFast routing algorithm. Each driver uses the lightweight ERP client on their mobile device to log into the ERP system and recover the day s ordered deliveries with addresses. A navigation aid gives drivers directions to each location. Once a driver reaches a delivery site, his list contains all the information needed to receive payment using the Payment Pebble. The Payment Pebble is used to process the transaction and the results are returned to the mobile ERP client, which then drives automatic reconciliation of the transaction in the ERP backend system. Reducing the number of steps, reducing paper work, and integrating card payment helps the company live up to its mission to be fast, efficient and affordable. Figure 8 Payment flow in a SpeedFast Couriers delivery and payment transaction, showing where the transaction is in the SpeedFast Couriers app (blue border) and where it is in the Payment Pebble app (red border). Payment Pebble Companion App API thumbzup 2014 6
3. Overview of the API A third party app registers intent on Android, or equivalent on other platforms, to the Payment Pebble app with the payment data. This launches the Payment Pebble app to process the payment. Upon completion of the transaction, the third party app needs to retrieve the response and follow its flow accordingly. The transaction happens under the control of the Payment Pebble itself, ensuring that all aspects of the transaction flow happen in a secure manner. The third party app cannot communicate directly with the Payment Pebble and the Payment Pebble app does not have authority over the success or failure of the transaction. The only information sent to the calling app by the Payment Pebble app is the transaction outcome. In addition, the Payment Pebble app may return an error code in the event that it is passed incorrect or missing data. Figure 9 App flow using the Companion API. Red arrows indicate encrypted communications. App developers only need to handle what happens in the first column. Payment Pebble Companion App API thumbzup 2014 7
3.1. Developing against the companion API To develop against the Companion API is a very simple process. It requires the use of the Payment Pebble emulator to allow emulated transactions during development. The sections below provide code examples and parameters for using the companion API. 3.2. Using the Payment Pebble Emulator app for development The Payment Pebble Emulator (hereafter emulator) is an Android app that developers can install on their development device in order to allow for development to take place without needing a Payment Pebble, API keys or back- end environment to be in place. The emulator returns a status code and appropriate status description if the emulated payment flow reaches the end, and error codes if launched with invalid data. The emulator does not send receipts via email or SMS. Figure 10 Payment Pebble Emulator Payment Pebble Companion App API thumbzup 2014 8
4. Conclusion The Payment Pebble Companion App API provides a viable mechanism to build mobile payment into another mobile application quickly and simply. There is no limit to how it can be used with existing or new apps to accept payment as part of a process that is supported using mobile apps. It offers rich user interfaces; easy access to value added services like vouchers or prepaid products with minimal development effort and requires no additional certification. v. 10 September 2014 Payment Pebble Companion App API thumbzup 2014 9