Android

The box-arr SDK is the Android client for the Box Retail Rails. It is a set of libraries a host embeds in its own Android app to enroll a device to a single merchant, sync the catalog, run a cart, take payments, and manage cashier sessions against the box’s retail-rails (RR) engine.

What ships

The AARs and the demo APK are versioned together and released as a set. The demo app is never published as a library; it ships only as the APK.

Install the demo APK

Download the latest demo APK from the Box downloads page (no auth required) and sideload it onto an Android device:

adb install -r box-demo.apk

Consume the libraries

Add the Potter Maven repository and depend on the modules you need. The libraries publish under the com.withpotter.box group:

dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
    maven { url = uri("https://maven.withpotter.com/releases") }
  }
}

dependencies {
  implementation("com.withpotter.box:box-commerce:0.1.0-alpha.3") // top-level entry point
  implementation("com.withpotter.box:box-arr-ui:0.1.0-alpha.3")   // Compose till UI
}

Modules

How the library works

box-arr is a headless SDK that runs inside the host’s own Android app, not a standalone app you install. A bank (or ISV) embeds the AARs into their existing Android application; that app owns the Activity/Application lifecycle, navigation, and screens. The core library ships no UI; it exposes a client your code drives.

One call wires every feature module together and returns a BoxArrClient:

val box = BoxArr.initialize(
  context,
  BoxConfig(
    backendUrl = "https://api.your-box.example", // the box engine
    tenantId = "acme-coffee",                    // the merchant this device serves
    paymentBridge = HostPaymentBridge(),         // your certified payment SDK (required)
    cloudProjectNumber = 123456789L,             // Play Integrity (required in production)
    tlsPins = listOf("sha256/…"),                // optional certificate pinning
  ),
)
 
// box.enrollment · box.sessions · box.catalog · box.payments

Key properties of the embedding model:

• Headless core. BoxArr.initialize(...) returns a BoxArrClient exposing enrollment, sessions, catalog, and payments. The host calls these from its own view models / screens.
• The host owns payments. BoxConfig.paymentBridge is a required delegate; the library never talks to a card reader itself. Your app plugs in its certified payment SDK; the library orchestrates the sale and posts the signed result to the engine.
• Every call is signed. The SDK generates a hardware-backed key in the Android Keystore at enrollment and signs each till → engine request with it, so the engine cryptographically trusts the device (see Device linking).
• Resume cheaply at launch. BoxArr.isEnrolled(context) is a cheap (SharedPreferences + Keystore) check the host can call on the main thread to decide whether to resume a linked terminal or run the pairing ceremony, without building the full client.
• Bring your own UI, or use the kit. box-arr-ui is an optional Compose module: a host that supplies no screens gets a fully-rendered, brand-themed store (BoxStorefront), a pairing screen (BoxTerminalLink), checkout, and sales history for free. A host that wants its own look drives the headless client directly and skips box-arr-ui.

Configuration reference

BoxConfig is immutable; build it once and hand it to BoxArr.initialize.

Payments are the host’s

PaymentBridge is a single-method contract your app implements so it can run its own certified payment flow; the library orchestrates the sale but never touches PAN, track data, PIN, CVV, or ARQC:

fun interface PaymentBridge {
  suspend fun requestPayment(request: PaymentRequest): PaymentOutcome
}

The library populates PaymentRequest.orderId and reference before calling your bridge; you supply the outcome. PaymentOutcome carries a status (SUCCESS / FAILED / PENDING / ABANDONED), the gatewayResponse, the Terminal that completed it, and an optional sanitized Authorization (masked card metadata only). The library signs and posts that result to the engine; the raw payment credentials never leave the host’s certified SDK.

Branding the terminal

When you use the box-arr-ui screens, the entire UI is driven by a single StorefrontTheme: colors, type, corner style, and catalog layout. Nothing is hardcoded in the screens (every color is a named role), so a re-skin touches only the theme.

The fastest path is to derive a whole coherent palette from one brand color:

import androidx.compose.ui.graphics.Color
import com.withpotter.box.ui.theme.*
 
val AcmeTheme = StorefrontTheme(
  // One seed color → primary, containers, surfaces, contrast (light or dark).
  brand = BoxBrand.fromSeed(Color(0xFF1B7F5A)),
  // Optional: the bank's own fonts and a global size scale.
  typeface = BoxTypeface(fontFamily = Inter, displayFamily = Fraunces, scale = 1f),
  // Optional: corner style. Default, Sharp (8dp), or Rounded.
  shapes = BoxShapes.Sharp,
  // Optional: catalog layout.
  layout = StoreLayout.GRID,
)

Then wrap the Box UI once, near the top of your Compose tree:

setContent {
  BoxStoreTheme(AcmeTheme) {
    // Your host shell + BoxStorefront(...) / BoxTerminalLink(...) render branded.
  }
}

Next steps