Die erste Transaktion ausführen

Eine Transaktion ist ein zweistufiger Vorgang: Zunächst erstellen Sie einen Transaktionskontext, anschliessend führen Sie ihn aus. Das SDK gibt bei der Erstellung einen TransactionContext zurück, den Sie an die Ausführungsfunktion übergeben. Durch diese Aufteilung können Sie die Transaktion vor Beginn der Ausführung abbrechen und den Zustand wiederherstellen, falls der App-Prozess abstürzt.

!Wichtig!

Um erfolgreiche Zahlungen durchzuführen, können Sie nur mit geraden Beträgen wie 6,00 testen.

1. Erstellen Sie eine Transaktionsanforderung

Eine Kaufanforderung enthält den Betrag, die Währung, eine Händlerreferenz für den Abgleich sowie eine oder mehrere Einzelposten:

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

Der Gesamtbetrag der Transaktion ergibt sich aus den Einzelposten. Verwenden Sie für Beträge BigDecimal – niemals Double oder Float.

2. Erstellen und Ausführen (Kotlin-Coroutinen)

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. Erstellen und ausführen (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. Eine laufende Ausführung abbrechen

Wenn der Benutzer den Zahlungsbildschirm verlässt, während das Terminal auf das Einführen der Karte wartet, fordern Sie den Dienst auf, den Vorgang abzubrechen:

Kotlin

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

Eine Abbruchaktion durch den Benutzer oder das Terminal wird als TransactionResult mit dem entsprechenden Ergebnis zurückgegeben – nicht als Ausnahme. TerminalCall.cancel() hebt lediglich das lokale Aufrufer-Handle auf; es stoppt das Terminal nicht.

Wichtige Begriffe

• TransactionContext: Der von createTransaction zurückgegebene Laufzeitkontext. Enthält transactionId.
• transactionId: Identifiziert den Laufzeitkontext. Wird für „execute“, „cancel“ und „recovery“ verwendet. Lokal für die SDK-Sitzung.
• transactionReferenceNumber: Die nach der Ausführung zurückgegebene Acquirer-/Zahlungsreferenz. Dies ist die dauerhafte Kennung – speichern Sie sie zusammen mit Ihrer Bestellung.

Diese drei sind unterschiedlich. Verwechseln Sie transactionId nicht mit transactionReferenceNumber.

Häufige Fallstricke

• Ausführung ohne Erstellung: executeTransaction erfordert ein transactionId aus einem vorherigen createTransaction-Aufruf.
• Wiederverwendung eines transactionId: Jeder Kontext ist nur einmal verwendbar. Erstellen Sie pro Transaktion einen neuen.
• Float-basierte Beträge: Führen zu Rundungsfehlern. Verwenden Sie immer BigDecimal.
• Fehlende Händlerreferenz: Die Abstimmung wird mühsam. Legen Sie immer ein eindeutiges merchantReference fest.
• Ablehnung als Fehler behandeln: Ablehnungen sind Geschäftsergebnisse bei TransactionResult, keine TerminalException-Fälle.

Mehr als nur der Kauf

Das gleiche „Create/Execute“-Muster gilt auch für andere Vorgänge im Zahlungsbereich:

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)

Jede gibt einen TransactionContext zurück, den Sie dann an executeTransaction übergeben.

Das vollständige Anforderungsschema, die Optionen für einzelne Zeilen und die Ergebnistypen finden Sie in der Terminal-API-Referenz.