Getting Started

Prerequisites

Before integrating PAaS 2, make sure you have:

1. A Westpay Android payment terminal with the Payment Application installed.
2. The paaslib_2.0.11.aar library.
3. Android Studio or an equivalent Android build environment.
4. Terminal ID, configuration host, and authorisation host values from Westpay.
5. Agreement with Westpay on the package/activity that the Payment Application should launch.

Step 1 - Expose the Launch Activity

The terminal is locked down for payment security, so the merchant does not manually launch apps. The Westpay Payment Application launches your PAaS app. Add the PAaS signature action to the activity that should be started.

xml
<activity
    android:name=".MainActivity"
    android:exported="true"
    android:label="@string/app_name">
    <intent-filter>
        <action android:name="se.westpay.paaslib.SIGNATURE" />
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

Step 2 - Create a Shared Terminal Instance

Create the PAaS library instance in your Android Application class so activities and fragments can access the same terminal object.

kotlin
class PaasApplication : Application() {
    lateinit var terminal: CarbonTerminal
        private set

    override fun onCreate() {
        super.onCreate()
        terminal = CarbonTerminal()
    }
}

Step 3 - Register with the Payment Service

Call register before using PAaS functions. Registration creates the resources required for communication with the Payment Application service.

kotlin
val terminal = (requireActivity().application as PaasApplication).terminal

val registered = terminal.register(
    requireContext(),
    object : RegisterResponseHandler {
        override fun onRegisterCompleted(success: Boolean) {
            Log.i("PAaS", "Payment service connected: $success")
        }
    }
)

if (!registered) {
    showError("Unable to register payment terminal")
}

Step 4 - Initialise the Terminal

initialise prepares the terminal to process transactions. It downloads configuration if needed and performs host login. The method returns immediately; the final outcome is delivered through InitialisationResponseHandler.

kotlin
val settings = TerminalSettings(
    terminalId = "80000001",
    authHosts = arrayOf("185.27.171.42:55144"),
    configHosts = arrayOf("185.27.171.42:55133"),
    language = "sv-SE",
    forceLogin = false
)

val started = terminal.initialise(
    settings = settings,
    response = object : InitialisationResponseHandler {
        override fun onInitialisationCompleted(result: InitialisationResponse) {
            val terminalStatus = result.getTerminalStatus()
            Log.i("PAaS", "Initialisation completed: $terminalStatus")
        }
    },
    notification = object : NotificationHandler {
        override fun onNotification(event: NotificationEvent, info: String) {
            Log.i("PAaS", "Notification: $event $info")
        }
    }
)

if (!started) {
    showError("Initialisation request was not accepted")
}

The Payment Application does not take over the screen during initialisation. Do not bring your PAaS app to the foreground from notification callbacks, because that can disturb Payment Application work.

Step 5 - Register a Transaction Result Launcher

PAaS 2 starts transactions through Android Intents. Register the launcher before starting a transaction.

kotlin
private lateinit var transactionLauncher: ActivityResultLauncher<Intent>

transactionLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        val app = requireActivity().application as PaasApplication
        val response = app.terminal.createTransactionResponseFromIntent(result.data)
        handleTransactionResponse(response)
    } else {
        showError("Transaction was cancelled")
    }
}

Step 6 - Start a Purchase

Create a PurchaseRequest, convert it to an Intent, and launch the Payment Application.

kotlin
val request = PurchaseRequest(
    currencyId = Constants.CURRENCY_ID_NUMBER_DEFAULT,
    totalAmount = 10000,
    saleId = "sale-1001",
    loyaltyApplications = emptyArray(),
    paymentMethod = "",
    cashBackAmount = 0,
    tipAmount = 0,
    maximumTipAmount = 0,
    maximumTipPercent = 100,
    allowSkipTip = SkipTipOptions.NO
)

request.setDisabledFeatures(arrayOf<PaymentFeatures>())

val intent = terminal.createIntentForTransaction(request)
if (intent != null) {
    transactionLauncher.launch(intent)
}

Step 7 - Print Receipts

After a completed transaction, print the cardholder and merchant receipts required for the transaction type and payment method.

kotlin
val printJob = terminal.startPrintJob(requireContext())

printJob.printTextLine(
    left = "Westpay",
    center = null,
    right = null,
    monospace = false,
    bold = true
)

printJob.printTextLine(
    left = "Approved",
    center = null,
    right = "100.00 SEK",
    monospace = true,
    bold = false
)

val status = printJob.finish()
Log.i("PAaS", "Printer status: $status")

Step 8 - Notify Exit

Call notifyExit before closing your app. This lets the Payment Application return to its main activity.

kotlin
val app = requireActivity().application as PaasApplication
app.terminal.notifyExit(requireContext())
requireActivity().finishAffinity()

Integration Checklist

• Launch activity includes se.westpay.paaslib.SIGNATURE.
• CarbonTerminal is shared from the Android Application class.
• register succeeds before initialise.
• initialise response is handled before enabling payment actions.
• Transaction result launcher is registered before launching payment.
• Request amounts and currency values match Westpay expectations.
• Receipts are printed or stored according to merchant requirements.
• notifyExit is called before the PAaS app exits.