App development

Rootline allows you to run your own app on the payment device. The payment devices Rootline offers are the A920Pro, A77 and A35 from PAX running a modified Android 10 or later.

Rootline offers the Connect SDK to integrate payments within your app.

PAX Developer Portal

Your app will be published through the PAX Developer Portal. The below steps describe how to register with PAX as a developer and release your app.

Registering with PAX

To publish your own app you need to register with PAX as a developer using the following link: https://paxemea.whatspos.com/developer. After you have registered with PAX, inform our support team by sending an email to support@rootline.com and provide the email address that was used to create the PAX developer account. Our team will link your developer account accordingly.

Adding and publishing an app in the PAX Developer Portal

In the PAX Developer Portal click on "+ NEW APP" and provide the name of your app. Upload the latest version of your APK and choose the app type:

Normal app: a standard Android app that will run on the payment device.
Parameter app: an app that will receive parameters from the platform, for example to push configurations. You need to integrate with the PAX Store SDK. You will also need to provide the template file in xml format.

Fill out the remainder of the required details such as:

App icon
Business Category (e.g. Point of Sale Management)
Model (PAX: A920Pro, A77, A35)
App Name
Short description
Description
Screenshots

Lastly you can save the app details or you can submit the version for approval. When you submit your app for approval, the app will be made available for distribution to the payment devices. You distribute the published app to specific payment devices through the Rootline API.

App distribution

Use the Apps and Payment Devices APIs to create the app and its versions in Rootline and install them on payment devices.

Create an app

After publishing your app on PAX, create the app in Rootline using the POST /v1/apps request. The package_name must match the Android package name you published on PAX.

curl 'https://config-api.staging.rootline.com/v1/apps' \
  --request POST \
  --header 'content-type: application/json' \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23' \
  --data '{
    "display_name": "Your app name",
    "package_name": "com.merchant.app"
  }'

Create an app version

After that, or when updating the app version, create the version in Rootline using the POST /v1/apps/{app_id}/app-versions request. version_code is the monotonic ordering key, increase the version_code and version for every new version.

curl 'https://config-api.staging.rootline.com/v1/apps/app_4MOgDpxvtIbL2mJJwNPdxZ/app-versions' \
  --request POST \
  --header 'content-type: application/json' \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23' \
  --data '{
    "version": "1.0.0",
    "version_code": "1"
  }'

tip

For versioning, Semantic Versioning MAJOR.MINOR.PATCH is recommended.

Add an app to a payment device

Then you can assign the app version to a payment device by using the POST /v1/payment-devices/{payment_device_id}/apps request:

curl 'https://config-api.staging.rootline.com/v1/payment-devices/device_1RCfEQ9KCY0chTiZ1QuSiN/apps' \
  --request POST \
  --header 'content-type: application/json' \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23' \
  --data '{
    "app_version_id": "appver_1OMXvsK6WYM6i47ELoH3s7"
  }'

warning

An app can be installed on a payment device only once. Update the installed app to change its version.

Update an app version on a payment device

When your app is already on the payment device and you want to update the version, make a PATCH /v1/payment-devices/{payment_device_id}/apps/{payment_device_app_id} request:

curl 'https://config-api.staging.rootline.com/v1/payment-devices/device_1RCfEQ9KCY0chTiZ1QuSiN/apps/appdev_1NUZfweIVsX0HIQ5Vhx7gc' \
  --request PATCH \
  --header 'content-type: application/json' \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23' \
  --data '{
    "app_version_id": "appver_1OMXvsK6WYM6i47ELoH3s8"
  }'

Uninstall an app from a payment device

If you want to uninstall your app from a device, make a DELETE /v1/payment-devices/{payment_device_id}/apps/{payment_device_app_id} request. The response is the installed app as it was before removal.

curl 'https://config-api.staging.rootline.com/v1/payment-devices/device_1RCfEQ9KCY0chTiZ1QuSiN/apps/appdev_1NUZfweIVsX0HIQ5Vhx7gc' \
  --request DELETE \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23'

Check the installation status

When retrieving a payment device, you can see the status of the installed app: pending, installed or failed. Rootline schedules the update to the payment device immediately and sets the status to pending. When the device is offline, the update will land as soon as it gets back online.

If the status is failed, Rootline was not able to push the app to the payment device, for example due to the version not being available in PAX or the device rejecting the install.

curl 'https://config-api.staging.rootline.com/v1/payment-devices/device_1RCfEQ9KCY0chTiZ1QuSiN' \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23'