Running your first transaction

A transaction is a two-phase operation: first you create a transaction context, then you execute it. The SDK returns a TransactionContext from creation that you pass into execute. This split lets you cancel before execution starts and recover state if the app process dies.

!Important!

You only can test with even amounts like 6.00 to run successful payments.

1. Build a transaction request

A purchase request carries the amount, currency, a merchant reference for reconciliation, and one or more line items:

kotlin

val request = TransactionRequest.purchase(
    BaseTransactionRequest.builder()
        .currency("CHF")
        .merchantReference("order-123")
        .addLineItem(
            PaymentLineItem.builder("item-1", BigDecimal("10.00"))
                .name("Demo item")
                .build()
        )
        .build()
)

The total transaction amount is derived from the line items. Use BigDecimal for amounts — never Double or Float.

2. Create and execute (Kotlin coroutines)

kotlin

lifecycleScope.launch {
    try {
        val context = sdk.terminal.payments.createTransaction(request)
        val result = sdk.terminal.payments.executeTransaction(context.transactionId)

        if (result is PurchaseResult && result.outcome == TransactionOutcome.APPROVED) {
            val ref = result.transaction?.transactionReferenceNumber
            // Persist ref against your order
        } else {
            // Handle declined, cancelled, or failed outcome
        }
    } catch (error: TerminalException) {
        // Technical failure — connection lost, service crashed, etc.
    }
}

3. Create and execute (Java callback)

java

sdk.getTerminal().getPayments().createTransaction(
    request,
    new TerminalCallback<TransactionContext>() {
        @Override
        public void onSuccess(TransactionContext context) {
            sdk.getTerminal().getPayments().executeTransaction(
                context.getTransactionId(),
                new TerminalCallback<TransactionResult>() {
                    @Override
                    public void onSuccess(TransactionResult result) {
                        // Inspect outcome
                    }

                    @Override
                    public void onFailure(TerminalException error) {
                        // Technical failure
                    }
                }
            );
        }

        @Override
        public void onFailure(TerminalException error) {
            // Technical failure during create
        }
    }
);

4. Cancel an execution in progress

If the user backs out of the payment screen while the terminal is waiting for card presentation, ask the service to stop:

kotlin

val cancellation = sdk.terminal.payments.cancelTransactionExecution(context.transactionId)

User or terminal cancellation comes back as a TransactionResult with the corresponding outcome — not as an exception. TerminalCall.cancel() only cancels the local caller handle; it does not stop the terminal.

Key terminology

• TransactionContext: the runtime context returned by createTransaction. Carries the transactionId.
• transactionId: identifies the runtime context. Used for execute, cancel, and recovery. Local to the SDK session.
• transactionReferenceNumber: the acquirer/payment reference returned after execution. This is the durable identifier — store it against your order.

These three are distinct. Do not conflate transactionId with transactionReferenceNumber.

Common pitfalls

• Executing without creating: executeTransaction requires a transactionId from a prior createTransaction call.
• Reusing a transactionId: each context is single-use. Create a new one per transaction.
• Float-based amounts: causes rounding errors. Always use BigDecimal.
• Missing merchant reference: reconciliation becomes painful. Always set a unique merchantReference.
• Treating decline as an error: declines are business outcomes on TransactionResult, not TerminalException cases.

Beyond purchase

The same create/execute pattern applies to other payment-domain operations:

kotlin

val refund       = sdk.terminal.payments.createRefund(refundRequest)
val capture      = sdk.terminal.payments.createReservationCapture(captureRequest)
val adjustment   = sdk.terminal.payments.createReservationAdjustment(adjustmentRequest)
val cancellation = sdk.terminal.payments.createReservationCancellation(cancellationRequest)
val voidContext  = sdk.terminal.payments.createVoid(voidRequest)

Each returns a TransactionContext you then pass to executeTransaction.

For the full request schema, line-item options, and result types, see the Terminal API reference.