Überprüfung des Transaktionsergebnisses

Nachdem executeTransaction abgeschlossen ist, gibt das SDK einen TransactionResult zurück. Die Überprüfung umfasst die Überprüfung des Ergebnisses, die Speicherung der Referenznummer sowie die Unterscheidung zwischen geschäftlichen Ergebnissen und technischen Fehlern.

1. In den spezifischen Ergebnistyp umwandeln

TransactionResult ist eine geschlossene Hierarchie. Führen Sie eine Typumwandlung in den konkreten Typ für die von Ihnen ausgeführte Operation durch:

Kotlin

val result = sdk.terminal.payments.executeTransaction(context.transactionId)

when (result) {
    is PurchaseResult              -> handlePurchase(result)
    is RefundResult                -> handleRefund(result)
    is ReservationCaptureResult    -> handleCapture(result)
    is VoidResult                  -> handleVoid(result)
    else                           -> { /* unexpected result type */ }
}

2. Je nach Ergebnis weitermachen

Jedes Ergebnis enthält ein TransactionOutcome. Behandeln Sie jeden Wert explizit – gehen Sie nicht davon aus, dass „nicht genehmigt“ gleichbedeutend mit „Fehlschlag“ ist:

Kotlin

when (result.outcome) {
    TransactionOutcome.APPROVED  -> { /* success — proceed */ }
    TransactionOutcome.DECLINED  -> { /* issuer or acquirer declined */ }
    TransactionOutcome.CANCELLED -> { /* user or terminal cancelled */ }
    TransactionOutcome.FAILED    -> { /* business-level failure */ }
}

Eine abgelehnte oder stornierte Zahlung ist ein normales Geschäftsergebnis und keine Ausnahme.

3. Die Transaktionsreferenznummer speichern

Nach der Genehmigung extrahieren und speichern Sie die transactionReferenceNumber. Dies ist die Referenz des Acquirers, die für den Abgleich, Rückerstattungen und Supportfälle verwendet wird:

Kotlin

if (result.outcome == TransactionOutcome.APPROVED) {
    val ref = result.transaction?.transactionReferenceNumber
        ?: error("Approved transaction missing reference number")

    // Store ref against your order in your backend
}

transactionReferenceNumber unterscheidet sich von transactionId. Speichern Sie die Referenznummer, nicht die Transaktions-ID.

4. Sonstige technische Störungen

Infrastruktur- und SDK-Fehler werden als Ausnahmen des Aufrufs selbst gemeldet, nicht als TransactionResult-Werte:

Kotlin

try {
    val result = sdk.terminal.payments.executeTransaction(transactionId)
    // ... inspect result.outcome ...
} catch (e: TerminalException) {
    // Transport, service crash, timeout — typically retryable
} catch (e: AtiSdkException) {
    // SDK connection or setup issue — reconnect required
}

TransactionResult gibt geschäftliche Ergebnisse an (genehmigt, abgelehnt, storniert, fehlgeschlagen).
TerminalException ist ein technischer Fehler beim Aufruf.
AtiSdkException ist ein Fehler im SDK-Lebenszyklus (keine Verbindung, Bindung verloren).

Leiten Sie jeden Pfad über eine andere Benutzeroberfläche weiter: Bei erfolgreichen Ergebnissen erfolgt die Weiterleitung zum Bestätigungs- oder Ablehnungsbildschirm; bei technischen Fehlern erfolgt die Weiterleitung zu einem Wiederholungsversuch.

5. Verwaiste Transaktionen beim Systemstart wiederherstellen

Falls Ihr App-Prozess mitten in einer Transaktion beendet wurde (Speicherengpass während der Interaktion mit dem Karteninhaber), wurde das Ergebnis möglicherweise erst nach dem Beenden Ihres Prozesses erzeugt. Überprüfen Sie dies daher stets beim Start, bevor Sie eine neue Transaktion einleiten:

Kotlin

val lastResult = sdk.terminal.payments.getLastResult()
if (lastResult.state == LastPaymentResultState.FOUND) {
    val recovered = lastResult.result
    // Reconcile against the order you initiated last
}

Wird dieser Schritt übersprungen, besteht die Gefahr, dass dem Karteninhaber der Betrag doppelt belastet wird.

Checkliste zur Überprüfung

TransactionResult in seinen konkreten Untertyp umwandeln
Bei jedem TransactionOutcome-Wert verzweigen, nicht nur bei APPROVED
Speichere transactionReferenceNumber bei der Genehmigung entsprechend deiner Reihenfolge
Behandle TerminalException und AtiSdkException auf separaten Pfaden
Rufe getLastResult() beim Start der App und nach dem erneuten Verbindungsaufbau auf

Häufige Fallstricke

Nicht genehmigte Ergebnisse als Ausnahmen behandeln: Ablehnungen sind normale Ergebnisse, keine Fehler.
transactionId statt transactionReferenceNumber speichern: Die Referenznummer ist die dauerhafte Kennung; die Transaktions-ID ist nur innerhalb der SDK-Sitzung gültig.
getLastResult() überspringen: führt zu Doppelbelastungen, wenn die App während einer Transaktion beendet wird.
Ein einziger Catch-Block für beide Ausnahmetypen: TerminalException und AtiSdkException erfordern unterschiedliche Wiederherstellungspfade.
Annahme, dass transaction nicht null ist: Bei abgelehnten oder fehlgeschlagenen Ergebnissen kann dieser Wert fehlen – führen Sie vor dem Auslesen der Referenz eine Nullprüfung durch.

Weitere Informationen:

Die vollständige Ergebnis-Hierarchie, alle Ergebniswerte und die Semantik der Wiederherstellung finden Sie in der Terminal-API-Referenz.

Überprüfung des Transaktionsergebnisses​

Überprüfung des Transaktionsergebnisses