Transactions

Transaction Flow

PAaS 2 transactions use Android Intents:

1. Your app creates a transaction request.
2. CarbonTerminal.createIntentForTransaction converts it to an Intent.
3. Your app launches the Payment Application with ActivityResultLauncher.
4. The Payment Application performs the secure payment flow.
5. Your app receives the result and calls createTransactionResponseFromIntent.
6. Your app handles approval, decline, receipts, and local order state.

Register the Result Launcher

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 cancelled")
    }
}

Purchase Request

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)
}

Refund Request

Use a refund request when returning funds to the cardholder or supported payment method. Include the original transaction reference when your flow requires it.

kotlin
val request = RefundRequest(
    currencyId = Constants.CURRENCY_ID_NUMBER_DEFAULT,
    totalAmount = 4500,
    saleId = "refund-1001",
    loyaltyApplications = emptyArray(),
    paymentMethod = "",
    transactionReference = originalTransactionReference
)

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

Transaction Response

The returned TransactionResponse contains outcome, transaction identity, receipts, payment details, and error/denial details.

kotlin
private fun handleTransactionResponse(response: TransactionResponse) {
    when (response.getError()) {
        TransactionError.NONE -> {
            completeSale(
                transactionId = response.getTransactionId(),
                terminalId = response.getTerminalId(),
                amount = response.getTotalAmount()
            )
            printReceipts(response)
        }
        else -> {
            showError("Payment failed: ${response.getError()}")
        }
    }
}

Receipt Handling

The exact receipt content depends on transaction type and payment method. At minimum, card-payment receipts should include:

• Reference number
• Verification and authorisation method
• Card name
• Whether the card was contactless or chip
• Denial reason when declined
• EMV data such as AID, TVR, and TSI

Alternative payment method receipts should include:

• Reference number
• Payment method

Print Text Receipt

kotlin
private fun printReceipts(response: TransactionResponse) {
    val printJob = terminal.startPrintJob(requireContext())

    printJob.printTextLine("Westpay", null, null, monospace = false, bold = true)
    printJob.printTextLine("Transaction", null, response.getTransactionId(), monospace = true, bold = false)
    printJob.printTextLine("Amount", null, response.getTotalAmount().toString(), monospace = true, bold = false)

    val status = printJob.finish()
    Log.i("PAaS", "Receipt print status: $status")
}

Print Bitmap Receipt

kotlin
fun printReceiptImage(context: Activity, image: Bitmap) {
    lifecycleScope.launch {
        val success = withContext(Dispatchers.Default) {
            val printJob = terminal.startPrintJob(context)
            val printed = printJob.printImage(image)
            val status = printJob.finish()
            printed && status == PrinterStatus.OK
        }

        if (!success) {
            showError("Unable to print receipt")
        }
    }
}

Last Transaction Result

Use getLastTransactionResult when your app needs to recover the final transaction outcome after interruption or uncertainty.

kotlin
terminal.getLastTransactionResult(
    object : TransactionResponseHandler {
        override fun onTransactionCompleted(result: TransactionResponse) {
            handleTransactionResponse(result)
        }
    }
)