Carbon SDK

Run your own application

Prototype, deploy and run your own application directly on our payment terminal. - How? On this page you will find information on how its achieved.

How can this be used and what is the catch?

To keep thing simple we limit you as little as possible
We make sure to protect the PCI-related parts and supply you with a set of functions that can be used to perform secure, reliable card payment transactions Other than that the sky is the limit. Examples of possible implementations are:
  • Build an ECR-application directly in the terminal, combining the two into a all-in-one solution
  • Create your own restaurant solution where waiter manages the table directly in the terminal and the customer pays the bill at the table
  • Move your RMA system into the terminal and take payments directly during on-site visits

So, how does it work?

The process is fairly simple and straight forward:
  1. After system boot the terminal performs a few automatic checks and once ready starts the Payment Application (PA)
  2. Once ready, the PA launches your App and hands over the display and goes into idle
  3. When your App starts you supply the PA with a set of instructions that will be used later to perform payments
  4. Your App is now in control of the terminal and can be used to operate your application without any restrictions
  5. When ready your App sends a request to the PA to perform a card payment

Sounds confusing?

Don't worry, to keep things simple we have created a Payment API with functions that enable you to perform payment related operations, without using specific intents etc. We also give you access to a fully functional sample App that you can compile and deploy to get a better understanding.

The process - from development to production

To make things manageable on your, and our end, we have set up a a few steps and guidelines that is good to know about

  1. Development

    • You are responsible for your own development, meaning that you are responsible for debugging, testing, maintaining and troubleshooting your code.
    • Westpay maintain the API that gives you access to card payments and non-native android hardware like the printer, card-reader and low-level settings.

  2. Deployment

    • You compile your application as .APK and sends this to your contact person at Westpay./li>
    • Westpay validates the content and production sign the APK once per week. The time slot for last delivery is Wednesdays 12:00 (GMT+1) each week.
    • Westpay will if no other info is communicated, make the package available via Westpay Access no later than 24h after last delivery time slot if no issues is found with the package.

  3. Production

    • You are responsible to create and maintain the updates for your terminals via Westpay Access and of triggering the updates locally on the terminal(s).
    • You are responsible of supplying Westpay with adequate information like logs upon support requests.
    • Westpay is responsible for the parameters used by the Payment Application that is required for card payments.

Development environment

Even if it would be possible to write your App against any Android phone device we have the following minimum requirements so that we later on can give you adequate support.

  • A modern IDE software like Visual Studio 2017-2019 or Android Studio
  • Android API Level 23 or lower (Our terminals run on Android 6)
  • A Westpay Carbon development terminal
Q:
What is a development terminal?
A:

A development terminal (also called: test terminal) is a device with a custom OS and firmware that allows you to deploy your own code to the terminal.

Q:
How is this different from production?
A:

Since our terminals main purpose is: secure, reliable card payments, we must make sure that nothing PCI-sensitive can be extracted from the terminal. We achieve this by locking down the accessibility to the system and its functions. As an example you are not able to install any applications on a production terminal on your own, it must be done via our systems.

Q:
What if i require external libraries?
A:

You can include any library that you want within your code. What you cannot do is to rely on other external applications.

Q:
Can I convert my dev terminal to production?
A:

Short answer: No.

Q:
Are there anything else I should know about dev VS prod?
A:

To make sure that you stay away from any PCI-related parts we analyze the manifest file that is part of all Android APK's. With this file we determine if we can approve the solution or not. If not we will tell you what you have to change before we can release it.

Do you need a development terminal?
Contact our sales department at sales@westpay.se

Getting started

Follow below guides on how you enable so that you can deploy and debug your application on our Carbon payment terminal(s)

1. Connect the terminal as per the description in the manual that comes with the terminal

2. After system start-up, when the screen states ”terminal closed” or ”terminal stängd” enter the following code on the terminal keypad: 147369 to enter the system menu.

3. Navigate to and select the menu option "Factory menu" with the terminal keypad.

4. Now enter the password 963741 via the terminal keypad and press the Enter key.

5. From the factory menu, select the option "Exit application".

6. From the launcher, press the screen to show the password input box.

7. Enter the code 963741 and complete the input with the enter key or the green arrow. A new menu will be shown, press the option P-test.

8. In P-test press the menu icon (three vertical dots) in the top right corner. Then select the menu option Extra Tools and then press the option Development Options.

9. In the development options view, scroll down to the header Debugging and activate USB debugging.

10. Now, connect your terminal to the PC using the included USB-C to USB-A cable. Unplug and then connect the cable again if you already had it connected to the terminal.

11. If a message box is shown when you connect your PC then tick the "Always allow" box.

12. In order to run a POS Application and open up for communication to the Payment Application the Operating mode needs to be set to “POSAPP”. From P-Test press “Exit” to return to the launcher.

13. From the launcher, press the screen to show the option “Start Payment Application”. Choose “Payment Application”.

14. The Payment Application starts, when the screen states “terminal closed” enter the following code on the terminal keypad: 147369 to enter system menu.

15. Navigate to and select menu option “Operating mode” with the terminal keypad.

16. Enter the password 963741 by using the terminal keypad and press the “Enter” key.

17. From the “Operating mode” menu, select the option “POSAPP” by using the terminal keypad.


1. Connect the terminal as per the description in the manual that comes with the terminal

2. After system start-up, when the screen states ”terminal closed” or ”terminal stängd” enter the following code on the terminal keypad: 147369 to enter the system menu.

3. Navigate to and select the menu option “Status” by using the terminal keypad.

4. In the Status menu option, navigate by pressing “NEXT” until “Network Info” is shown, note the IP address.

5. Exit the “Status” menu by pressing the red button on the terminal keypad once, you will get back to the “System functions” menu.

6. Navigate to and select menu option “Operating mode” with the terminal keypad.

7. Enter the password 963741 by using the terminal keypad and press the “Enter” key.

8. From the “Operating mode” menu, select the option “POSAPP” by using the terminal keypad.

Useful information

Below you will find some useful information about tools and commands that you can use when you test your solution on our application.

To get access to our test environment you should use the following connection information

SPDH: 185.27.171.42:55122
PPL: 185.27.171.42:55111

Update the Payment Application

During your development it can be required that you update the current Payment Application to enable new functionality. Follow below steps if you are uncertain on how this is managed in Android

  1. Close the running Payment Application via the "Factory menu" or the following adb-command:
    adb shell "ps | grep WestPA | sed 's/..........\([0-9]*\).*/\1/g' | xargs kill"
  2. Uninstall previous Payment Application

    3. adb uninstall Westpay.WestPA

    Output (example)

    Success
  3. Install new version of Payment Application

    4. (Simply drag and drop the apk into the ADB terminal window to append the correct file path

    adb install c:\temp\WPA-2.0.5.103.apk

    Output (example)

    /Volumes/Android/.. 4.8 MB/s (18669461 bytes in 3.701s)

    Success
  4. Start the Payment Application again via the launcher or the following adb-command:
    adb shell monkey -p Westpay.WestPA -c android.intent.category.LAUNCHER 1

Terminal settings

All settings in the terminal are stored in: /sdcard/West/BIT_OW/LocalConfig/config.d Some of these settings control the behavior of the terminal and can be good to know about.

To change any of the settings via adb shell simply copy below code, replace the variables with the setting and value that you want to use

adb echo Value > /sdcard/West/BIT_OW/LocalConfig/config.d/Setting

To view the value of any current setting, type below command in adb shell:

adb cat /sdcard/West/BIT_OW/LocalConfig/config.d/Setting

Settings

ApplicationMode
Controls in what mode the terminal will start
Possible values: EPAS, STANDALONE, NEXO, POSAPP
file content example: EPAS
PosApplicationPackageName
Package name of the broadcast receiver that will receive the start-up intent from the Payment Application
file content example: se.westpay.posapp
PosApplicationClassName
The class name of the broadcast receiver that will receive the start-up intent from the Payment Application
file content example: se.westpay.posapp.StartupReceiver
SuspendTimer
The number of seconds of no activity before the terminal will enter suspend mode, regardless of setting in the android system
Default value: 30
file content example: 0
SleepTimer
The number of seconds of no activity before the terminal will enter idle mode, regardless of setting in the android system
Default value: 30
file content example: 0
ScreenBrightness
Sets the screen brightness in percent (range 10-100), regardless of setting in the android system
Default value: 40
file content example: 100
EnableTipping
Enables or Disables an extra step during payment where the customer can add tip to the payment.
Default value: false
file content example: true

Important information

Any changes made during development is not automatically migrated into production. Please inform your contact at Westpay if any changes is required.

Android Debug Bridge (adb)

Android Debug Bridge (adb) is a versatile command-line tool that lets you communicate with a device. The adb command facilitates a variety of device actions, such as installing and debugging apps.

Read more about available commands here: https://developer.android.com/studio/command-line/adb

List terminal devices

adb devices

Output (example)

List of devices attached:

1043000510 device
View terminal debug log

adb logcat

Output (example)

01-31 22:54: D KeyguardUpdateMonitor: received

01-31 22:54: D KeyguardUpdateMonitor: handleBatteryUpdate

01-31 22:54: I chatty : uid=1000(system) Thread-2 expire 13 lines
View Payment Application events and POS intents

adb logcat | grep -e WestPA -e CarbonTerminal

Output (example)

Terminal logs

There are three different logs within the terminal, each log serve different purposes.

West Payment Application log

This log contains all information related to card payments and is the main log Westpay will request upon troubleshooting requests. You can access this log in a few different ways. This log is available in both development/test and production terminals. (No PCI sensitive information is stored in the log)

Access the log manually:
  1. Connect the terminal to the same network as your computer
  2. Find the terminals IP address via adb or the terminal system menu
  3. Open up a preferred web browser on your computer
  4. Navigate to the url: http://terminal-ip:4000/
  5. At the login window enter the code: 963741
  6. Select "View log" from the now visible menu options

Note that this log-view is only available if the Westpay Payment Application is running and your PC and terminal is connected to the same network.

Android system log (logcat)

Logcat is a command-line tool that dumps a log of system messages, including stack traces when the device throws an error and messages that you have written from your app with the Log class.

Logcat is not available in production

Production logs

A custom log available for production terminals where some of the regular logcat information is store along with low-level card operations.

This log is available in production but can only be accessed with instructions from Westpay