Ü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 weiterverfahren

Jedes Ergebnis enthält ein TransactionOutcome. Behandeln Sie jeden Wert ausdrücklich – gehen Sie nicht davon aus, dass „nicht genehmigt“ gleichbedeutend mit einem 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 stellt keine Ausnahme dar.

3. Speichern Sie die Transaktionsreferenznummer

Nach der Genehmigung extrahieren Sie bitte die Referenz transactionReferenceNumber und speichern Sie diese dauerhaft. 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 ausgegeben, 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 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
}

Wenn Sie diesen Schritt überspringen, besteht die Gefahr, dass dem Karteninhaber der Betrag doppelt in Rechnung gestellt wird.

Checkliste zur Überprüfung

TransactionResult in seinen konkreten Untertyp umwandeln
Bei jedem TransactionOutcome-Wert verzweigen, nicht nur bei APPROVED
Speichern Sie transactionReferenceNumber bei der Genehmigung entsprechend Ihrer Reihenfolge
Behandeln Sie TerminalException und AtiSdkException auf separaten Pfaden
Rufen Sie getLastResult() beim Start der Anwendung und nach dem erneuten Verbindungsaufbau auf

Häufige Fallstricke

Behandlung nicht genehmigter Ergebnisse als Ausnahmen: Ablehnungen sind normale Ergebnisse, keine Fehler.
Speicherung von transactionId anstelle von transactionReferenceNumber: Die Referenznummer ist die dauerhafte Kennung; die Transaktions-ID ist nur innerhalb der SDK-Sitzung gültig.
getLastResult() überspringen: Dies führt zu Doppelbelastungen, wenn die App während einer laufenden 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 sowie die Semantik der Wiederherstellung finden Sie in der Terminal-API-Referenz.

Überprüfung des Transaktionsergebnisses​

Überprüfung des Transaktionsergebnisses