In-Car Payments

Connected commerce around cars is a growing business area. The car is becoming a platform for services and applications, which are not only related to driving. The car is becoming a hub for services, which are related to the driver and passengers. This includes services like entertainment, navigation, and also payments. The car is becoming a wallet on wheels. Starfish provides Software Development Kits (SDK) which turn cars into mobile wallets and enable providers of in-car commerce experiences, with a convenient approach to implement their solutions.

High-level overview

In order to understand the integration of an In-Car Wallet, it is important to understand the context in which it is used. The following illustration shows the main building blocks and their primary interactions.

Car context

The car context revolves around the In-Car Wallet and the In-Car Applications that utilize it. Starfish provides two SDKs to simplify the development of these components.

In-Car Application

In-Car Applications enable commerce-related use cases such as parking, fueling, and food delivery. Typically offered by third-party providers, these apps are independent of the car manufacturer’s core offerings. To streamline implementation and ensure compatibility across providers, Starfish offers the Wallet Consumer SDK. This lightweight library provides a simple interface for integrating with the In-Car Wallet.

In-Car Wallet

The In-Car Wallet is a core component provided by car manufacturers. It securely stores payment methods, manages transactions, and offers a user interface for wallet interactions. While the wallet experience is tailored to the car manufacturer’s brand, Starfish’s Wallet SDK abstracts payment processing, enabling rapid development of fully certified in-car payment solutions.

Backends

Supporting the car context are backend services that handle business logic and third-party integrations.

Application backends

These services power In-Car Applications by implementing business logic and managing connections to third-party services, such as payment gateways and providers. It is important to understand that the Wallet itself only handles the authentication of the shopper for a payment. The actual payment processing is done by the application backend.

Wallet Service

The Wallet Service, provided by Starfish, manages wallet assets and interfaces with the payment ecosystem to ensure secure, seamless transactions.

Payment tokens

During a transaction, the In-Car Application prompts the driver or passenger to authenticate themselves to authorize the payment. Upon successful authentication, the In-Car Wallet generates a payment token. This token can be used by the app provider with their payment processing system to request the required authorization.

Getting started with app development

For the sake of simplicity, we are not focusing here on the implementation of In-Car Wallets, but on their use for In-Car Applications.

If you want to dive deeper into the implementation of the Wallet, please reach out to your account representative.

Prerequisites

We need a couple of extra things but they are easy to get; then we move focus to the app.

Your Commerce account

First, go to Hellgate.io and register for a sandbox account if you don’t have one yet. Once you’re in, you can head over to the Wallet Developer Settings section on the left menu bar and you should see your wallet credentials to get access to the app dependencies. It might take a second since the credentials are created for you just in time. Keep them around, you will need them for later, or come back to the page if you need them again.

The Wallet Simulator

Cars are notoriously hard to keep around in the office, so they don’t make good test instruments. Because of this we have developed a wallet simulator that works just like your car wallet would, with some extra functionality for testing purposes, and the obvious branding difference. It is Commerce wallet behind the scenes, so you can develop with confidence. To Install the simulator:

If you have a test device, head to the Simulator Play Store page and install it as usual.
If you are using the emulator, contact your account representative or reach out to our sales team via hellgate.io/demo to obtain the latest APK, then install it by dragging the APK file into your running emulator screen.

Once you have it installed, open the app and follow the quick instructions to configure it with your Commerce wallet account ID that you got in the previous step. Ignore the webhook field for the moment. And that is it, close the app, there is no save button, and you are ready to go. Now it’s time to move over to your own app and start a payment. We will follow up with some more screenshots of the simulator in action, to give you an idea what to expect.

When you start a payment from your app you will be prompted with an outcome; this is how you simulate the various possibilities, from a successful payment to an authentication failure.

Your app

Finally we get to do some code, but not a whole lot. If you have a running app, choose where you want to place your “pay now” button and follow along. If you do not have an app, you can start a template project from Android Studio. Go to File → New → New Project and select a template; the empty activity one is a good place to start.

Setting up the SDK dependency

There are several ways to declare an additional Maven repository and dependencies; here is one via settings.gradle.kts and app/build.gradle.kts. Grab the Maven credentials from your Commerce dashboard and include them in your Gradle files.

// in settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = URI.create("https://maven.hellgate.io/repository/sf-maven")
            credentials {
                username = "QUP6VG965A" // username from your dashboard
                password = "************" // password from your dashboard
            }
        }
    }
}

// in app/build.gradle.kts
dependencies {
    implementation("io.hellgate:hw.wallet-consumer-sdk:1.0.0")
}

The payment authentication code

Payments are initiated using everyday Android intents. We fill a io.hellgate.hw.consumer.PaymentData object and using standard intent launch plumbing we launch the intent. In essence, this is the whole function we need to implement:

fun makePayment(
  scope: CoroutineScope,
  launcher: ManagedActivityResultLauncher<PaymentData, PaymentAuthenticationResult>,
) {
  scope.launch {
    launcher.launch(
      PaymentData(
        merchantRefId = "1234",
        signature = "TEST",
        amount = 10000,
        currencyCode = "USD",
        creditor = "Simple Store",
        subject = "Simple payment",
      ),
    )
  }
}

Now we also need to do something with the result. Our intent result is a io.hellgate.hw.consumer.PaymentAuthenticationResult, which can either be Success or Failure, and in case of a success, give us our payment token. Again, this does not mean the payment was completed, it just means it was authenticated, the actual payment should be done in your backend, but we will get there in a moment. For now lets just add a quick function to handle our result, in this case we will just print it out:

fun receiveResult(result: PaymentAuthenticationResult) {
  when (result) {
    is PaymentAuthenticationResult.Success ->
      Log.d("MainActivity", "Payment authentication successful, got the token: ${result.paymentToken}")
    is PaymentAuthenticationResult.Failure ->
      Log.d("MainActivity", "Received authentication failed")
  }
}

The UI code

From here on, it’s all standard Android development. Let’s create a simple button that calls our makePayment function:

@Composable
fun PaymentButton(  scope: CoroutineScope,  launcher: ManagedActivityResultLauncher<PaymentData, PaymentAuthenticationResult>,) {  Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->    Column(      modifier = Modifier        .padding(innerPadding)        .fillMaxSize(),      verticalArrangement = Arrangement.Center,      horizontalAlignment = Alignment.CenterHorizontally,    ) {      Button(onClick = { makePayment(scope, launcher) }) {        Text("Make a Payment")      }    }  }}

The only relevant piece is the onClick handler invoking our makePayment function:

Button(onClick = { makePayment(scope, launcher) })

So now all that is left is to add our button to the content of some activity:

setContent {
  val scope = rememberCoroutineScope()
  val launcher = rememberLauncherForActivityResult(PaymentIntentContract) { result ->
    receiveResult(result)
  }
  MyApplicationTheme {
    PaymentButton(scope, launcher)
  }
}

The important pieces here are the intent launcher initialization with our receiver function:

    val launcher = rememberLauncherForActivityResult(PaymentIntentContract) { result ->
        receiveResult(result)
    }

And displaying our button:

  PaymentButton(scope, launcher)

Putting it all together

If you started with the empty activity Android Studio template, the end result could look something like the code listing below. Of course in your own application, or if you used a different starter template, it will look different, but the important thing here is the pattern.

package team.starfish.myapplication

import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import androidx.activity.compose.ManagedActivityResultLauncher
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import io.hellgate.hw.consumer.PaymentAuthenticationResult
import io.hellgate.hw.consumer.PaymentData
import io.hellgate.hw.consumer.PaymentIntentContract
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.launch
import team.starfish.myapplication.ui.theme.MyApplicationTheme

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContent {
      val scope = rememberCoroutineScope()
      val launcher = rememberLauncherForActivityResult(PaymentIntentContract) { result ->
        receiveResult(result)
      }
      MyApplicationTheme {
        PaymentButton(scope, launcher)
      }
    }
  }
}

@Composable
fun PaymentButton(
  scope: CoroutineScope,
  launcher: ManagedActivityResultLauncher<PaymentData, PaymentAuthenticationResult>,
) {
  Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
    Column(
      modifier = Modifier
        .padding(innerPadding)
        .fillMaxSize(),
      verticalArrangement = Arrangement.Center,
      horizontalAlignment = Alignment.CenterHorizontally,
    ) {
      Button(onClick = { makePayment(scope, launcher) }) {
        Text("Make a Payment")
      }
    }
  }
}

fun makePayment(
  scope: CoroutineScope,
  launcher: ManagedActivityResultLauncher<PaymentData, PaymentAuthenticationResult>,
) {
  scope.launch {
    launcher.launch(
      PaymentData(
        merchantRefId = "1234",
        signature = "TEST",
        amount = 10000,
        currencyCode = "USD",
        creditor = "Simple Store",
        subject = "Simple payment",
      ),
    )
  }
}

fun receiveResult(result: PaymentAuthenticationResult) {
  when (result) {
    is PaymentAuthenticationResult.Success ->
      Log.d("MainActivity", "Payment authentication successful, got the token: ${result.paymentToken}")
    is PaymentAuthenticationResult.Failure ->
      Log.d("MainActivity", "Received authentication failed")
  }
}

You should now be able to simulate a payment authorization and get the token printed out. If you started from the Android Studio template, this is how the app should look:

More on PaymentData

The PaymentData data class contains the minimum information required to authenticate the payment. It is all you need to start a payment, plus a few extra properties to assist the actual wallet app with the information display.

data class PaymentData(
  val merchantRefId: String,  // unique transaction id, will not be displayed to the user
  val signature: String,     // for simulation use "TEST"
  val amount: Int,           // amount in minor currency unit
  val currencyCode: String,  // ISO 4217
  val creditor: String,      // display only; in production verified with signature
  val subject: String,       // description of the payment
)

Doing something with the result

Right now we are just printing out our result. But what we really want is to make a payment, and there are two possible courses of action:

You receive the payment token in your app and you send it back to your own backend for further processing
Preferred: you configure your account with a webhook that receives the payment token directly from Commerce, and you fetch the status from your frontend

When you created your Commerce account we also configured a simple backend simulator for you, which basically receives the token and simulates a payment. You can then use said backend server to fetch the payment status and update your app UI and behavior according to the new purchase that was just made. So this is what we will use in this guide. Because polling for a result is such a common action, the Wallet Consumer SDK provides a helper function named simplePolling that takes a URL and polls until it receives a successful result. We will leverage that function, punch in our backend simulator URL, and that will get us a result that honours what we selected as the outcome in the wallet simulator. We then replace the Success case in our receiveResult function with our polling function:

simplePolling("https://icp-wallet-backendsimulator.fly.dev/merchant/$merchantId/payment/${result.paymentId}")
  .onSuccess {
    Log.d("MainActivity", "Received payment status: $it")
  }

The whole thing, with a few extra logging statements and making our function suspend, now looks like this:

suspend fun receiveResult(result: PaymentAuthenticationResult) {
  Log.d("MainActivity", "Received result: $result")
  val merchantId = "hardwareStore123"
  when (result) {
    is PaymentAuthenticationResult.Success -> {
      Log.d("MainActivity", "Authentication: SUCCESS, Payment status: PENDING")
      Log.d("MainActivity", "Fetching payment status from merchant server")
      simplePolling("https://icp-wallet-backendsimulator.fly.dev/merchant/$merchantId/payment/${result.paymentId}")
        .onSuccess {
          Log.d("MainActivity", "Received payment status: $it")
        }
    }
    is PaymentAuthenticationResult.Failure ->
      Log.d("MainActivity", "Received authentication failed")
  }
}

This particular piece requires internet access. If you are trying this out in your existing app it is very likely that permission is already set, but if you started with the Android Studio template, don’t forget to add it to AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

One final piece: we made our receiveResult suspend because we are going out to the internet. So we need to update our launcher configuration to send that result through our coroutine scope:

            val launcher = rememberLauncherForActivityResult(PaymentIntentContract) { result ->
                scope.launch { receiveResult(result) }
            }

Final result

With the recent changes, our demo code leveraging our simulators should look similar to this:

package team.starfish.myapplication

import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import androidx.activity.compose.ManagedActivityResultLauncher
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import io.hellgate.hw.consumer.PaymentAuthenticationResult
import io.hellgate.hw.consumer.PaymentData
import io.hellgate.hw.consumer.PaymentIntentContract
import io.hellgate.hw.consumer.polling.simplePolling
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.launch
import team.starfish.myapplication.ui.theme.MyApplicationTheme

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContent {
      val scope = rememberCoroutineScope()
      val launcher = rememberLauncherForActivityResult(PaymentIntentContract) { result ->
        scope.launch { receiveResult(result) }
      }
      MyApplicationTheme {
        PaymentButton(scope, launcher)
      }
    }
  }
}

@Composable
fun PaymentButton(
  scope: CoroutineScope,
  launcher: ManagedActivityResultLauncher<PaymentData, PaymentAuthenticationResult>,
) {
  Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
    Column(
      modifier = Modifier
        .padding(innerPadding)
        .fillMaxSize(),
      verticalArrangement = Arrangement.Center,
      horizontalAlignment = Alignment.CenterHorizontally,
    ) {
      Button(onClick = { makePayment(scope, launcher) }) {
        Text("Make a Payment")
      }
    }
  }
}

fun makePayment(
  scope: CoroutineScope,
  launcher: ManagedActivityResultLauncher<PaymentData, PaymentAuthenticationResult>,
) {
  scope.launch {
    launcher.launch(
      PaymentData(
        merchantRefId = "1234",
        signature = "TEST",
        amount = 10000,
        currencyCode = "USD",
        creditor = "Simple Store",
        subject = "Simple payment",
      ),
    )
  }
}

suspend fun receiveResult(result: PaymentAuthenticationResult) {
  Log.d("MainActivity", "Received result: $result")
  val merchantId = "hardwareStore123"
  when (result) {
    is PaymentAuthenticationResult.Success -> {
      Log.d("MainActivity", "Authentication: SUCCESS, Payment status: PENDING")
      Log.d("MainActivity", "Fetching payment status from merchant server")
      simplePolling("https://icp-wallet-backendsimulator.fly.dev/merchant/$merchantId/payment/${result.paymentId}")
        .onSuccess {
          Log.d("MainActivity", "Received payment status: $it")
        }
    }
    is PaymentAuthenticationResult.Failure ->
      Log.d("MainActivity", "Received authentication failed")
  }
}

Getting Started

Payments

Tokens

Authentications

Wallets

High-level overview

Car context

In-Car Application

In-Car Wallet

Backends

Application backends

Wallet Service

Payment tokens

Getting started with app development

Prerequisites

Your Commerce account

The Wallet Simulator

Your app

Setting up the SDK dependency

The payment authentication code

The UI code

Putting it all together

More on PaymentData

Doing something with the result

Final result

​High-level overview

​Car context

​In-Car Application

​In-Car Wallet

​Backends

​Application backends

​Wallet Service

​Payment tokens

​Getting started with app development

​Prerequisites

​Your Commerce account

​The Wallet Simulator

​Your app

​Setting up the SDK dependency

​The payment authentication code

​The UI code

​Putting it all together

​More on PaymentData

​Doing something with the result

​Final result

High-level overview

Car context

In-Car Application

In-Car Wallet

Backends

Application backends

Wallet Service

Payment tokens

Getting started with app development

Prerequisites

Your Commerce account

The Wallet Simulator

Your app

Setting up the SDK dependency

The payment authentication code

The UI code

Putting it all together

More on PaymentData

Doing something with the result

Final result