Výsledky platby

Výsledek platby je reprezentován sealed třídou PaymentResult. Callback onPaymentResult v SecurePayButton.setup() i SecureGooglePayButton.setup() je vždy volán na hlavním vlákně (main thread).

PaymentResult

V praxi rozlišujte tieto typy výsledku:

Typ PaymentResult	Popis
PaymentResult.Paid	Platba bola dokončena a potvrzena.
PaymentResult.Authorized	Platba bola autorizovaná bankou (pre-autorizácia).
PaymentResult.Pending	Platba se stále zpracovává (mezistav).
PaymentResult.Cancelled	Platba bola zrušená alebo zamietnutá serverem.
PaymentResult.Failed	Chyba na strane knižnice počas platebního procesu.

Paid

Platba je úspěšně dokončená.

is PaymentResult.Paid -> {
    val transId = result.transId
    // Platba dokončena
}

Authorized

Platba bola autorizovaná (pre-autorizovaná) bankou. Ide o finálny stav. Zachytenie (settlement) platby vykoná obchodník samostatne pomocou štandardných endpointov /capturePreauth alebo /cancelPreauth.

is PaymentResult.Authorized -> {
    val transId = result.transId
    // Platba autorizovaná, čaká na zachytenie
}

PENDING

Platba ještě není finální, backend ji stále zpracovává. Finálnym stavom bude Paid, Authorized alebo Cancelled.

is PaymentResult.Pending -> {
    val transId = result.transId
    // Čekáme na finální stav
}

CANCELLED

Platba bola zrušená alebo zamietnutá serverem. Obsahuje identifikátor transakce a volitelný dôvod.

is PaymentResult.Cancelled -> {
    val transId = result.transId
    val reason = result.errorReason
    // Platba bola ukončena bez úhrady
}

Ak je výsledek PaymentResult.Cancelled, obsahuje odpověď i errorReason. V SDK je tento dôvod dostupný jako PaymentResult.Cancelled.errorReason.

Možné hodnoty errorReason

errorReason	Význam
CUSTOMER_CLICK	Zrušeno plátcem.
FRAUD_SUSPECTED	Podezření na podvod.
ESHOP_CANCELLED	Zrušeno obchodníkem.
PROVIDER_REPORT	Zrušeno providerem.
PROVIDER_TIMEOUT	Vypršel časový limit poskytovatele.
CUSTOMER_TIMEOUT	Vypršel časový limit platby.
ACS_TIMEOUT	Vypršel časový limit pro ověření.
INVALID_CARDNO_EXPIRY	Chybně zadané číslo karty alebo datum platnosti karty.
INVALID_CVC	Chybně zadaný CVC / CVV kód.
LIMIT_EXCEEDED	Limit karty byl překročen.
NO_FUNDS	Na účtu není dostatečný zůstatek.
REJECTED_BY_BANK	Platba bola zamietnutá bankou.
3DS_AUTH_FAIL	Ověření platby nebylo úspěšné.
NOT_SPECIFIED	Nespecifikováno.

Testování chybových scénářů

V dev režimu (devMode = true) můžete tieto hodnoty simulovat pomocí parametru errorReason v PaymentParams. Viz sekcii Simulace chybového dôvodu.

FAILED

Chyba na strane knižnice, která nastala počas platebního procesu. Na rozdíl od Cancelled (kde server aktivně zamítl platbu), Failed značí, že k dokončení platby vůbec nedošlo — napr. síťová chyba,...

Výsledek obsahuje objekt ComgateError s machine-readable kódem (code) a lidsky čitelnou zprávou (message).

is PaymentResult.Failed -> {
    val errorCode = result.error.code       // napr. "PAYMENT_NETWORK_ERROR"
    val errorMessage = result.error.message // napr. "Payment request failed due to a network error"
    // Zobrazení chyby používateľi
}

ComgateError

Všechny chyby jsou definovány jako podtypy sealed třídy ComgateError. Každý typ obsahuje:

• code — strojově čitelný identifikátor chyby
• message — lidsky čitelný popis v angličtině

Inicializace

Kód	Popis
DEVICE_ROOTED	Zariadenie je pravdepodobne rootované alebo inak pozmenené. Inicializácia je zablokovaná za účelom ochrany kartových dát. V devMode sa táto kontrola preskočí.
INIT_NETWORK_ERROR	Inicializace session selhala kvůli síťové chybě.
INIT_UNAUTHORIZED	Server vrátil HTTP 401 pri inicializácii — neplatná alebo expirovaná autorizácia.
INIT_FAILED	Inicializace session selhala (jiný než síťový dôvod).
APPLICATION_NOT_ALLOWED	Aplikace není povolena pro použitie SDK (package name není na allow-listu).

Zpracování platby

Kód	Popis
SESSION_NOT_INITIALIZED	Session nebola inicializována. Zavolejte nejprve initialize().
INVALID_CARD_DATA	Kartové údaje nejsou validní.
MISSING_CARDHOLDER_NAME	Jméno držitele karty nebylo poskytnuto.
PAYMENT_FAILED	Platba selhala (jiný než síťový dôvod).
PAYMENT_NETWORK_ERROR	Platební požadavek selhal kvůli síťové chybě.
PAYMENT_CREATE_FAILED	Vytvorenie platby selhalo.
POLLING_TIMEOUT	Kontrola stavu platby vypršela.
POLLING_NETWORK_ERROR	Kontrola stavu platby selhala kvůli síťové chybě.

Google Pay

Kód	Popis
GOOGLE_PAY_NOT_CONFIGURED	Google Pay není nakonfigurován.
GOOGLE_PAY_FAILED	Google Pay platba selhala.

Validácia polí

Kód	Popis
INVALID_PAN	Neplatné číslo karty.
INVALID_EXPIRY_MONTH	Neplatný měsíc expirace.
CARD_EXPIRED	Karta je expirovaná.
INVALID_CVV	Neplatný CVV kód.

SecurePaymentStatusView

Komponenta SecurePaymentStatusView slouží k zobrazování stavových hlášek platby (úspěch, spracovania, chyba). Začíná ve skrytém stavu (GONE) a zobrazí se po zavolání showStatus().

Zobrazení stavu z PaymentResult

Metoda showStatus(PaymentResult) automaticky rozpozná typ výsledku a zobrazí odpovídající styl:

val statusState = rememberPaymentStatusState()

// Automatické mapování PaymentResult na stavovou zprávu
statusState.showStatus(paymentResult)

// V Composable:
SecurePaymentStatusView(state = statusState)

PaymentResult	Chování
Paid	Zobrazí lokalizovanou zprávu „Paid“ se zeleným stylem (úspěch).
Authorized	Zobrazí lokalizovanú správu „Authorized" so zeleným štýlom (úspech).
Pending	Zobrazí lokalizovanou zprávu „Processing" s oranžovým stylem (spracovania).
Cancelled	Zobrazí errorReason s červeným stylem (chyba).
Failed	Zobrazí error.message s červeným stylem (chyba).

Skrytí view

statusState.clear()

Stylizace

Podrobnosti o stylizaci SecurePaymentStatusView prostredníctvom update bloku, setter metod a XML atribútů nájdete v sekcii Stylizace komponent.

Kompletný príklad spracovania výsledků

@Composable
private fun PaymentResultHandler(session: ComgateSecureSession) {
    val statusState = rememberPaymentStatusState()
    var resultText by remember { mutableStateOf("") }
    var resultVisible by remember { mutableStateOf(false) }

    // ... (karetní pole, kolektor, tlačidlo — viz sekce Kartové údaje)

    // Spracovanie výsledku platby:
    fun handlePaymentResult(result: PaymentResult) {
        when (result) {
            is PaymentResult.Paid -> {
                statusState.showStatus(result)
                resultVisible = true
                resultText = "Platba dokončena\nTransId: ${result.transId ?: "-"}"
            }

            is PaymentResult.Authorized -> {
                statusState.showStatus(result)
                resultVisible = true
                resultText = "Platba autorizovaná\nTransId: ${result.transId}"
            }

            is PaymentResult.Pending -> {
                statusState.showStatus(result)
                resultVisible = true
                resultText = "Platba se zpracovává\nTransId: ${result.transId ?: "-"}"
            }

            is PaymentResult.Cancelled -> {
                resultVisible = false
                statusState.showStatus(result)
                // Volitelne: Toast.makeText(context, "Platba zrušená: ${result.errorReason ?: "bez detailu"}", Toast.LENGTH_LONG).show()
            }

            is PaymentResult.Failed -> {
                resultVisible = false
                statusState.showStatus(result)
                Log.w("PaymentResult", "Failed: ${result.error.code} — ${result.error.message}")
                // Volitelne: Toast.makeText(context, "Chyba: ${result.error.message}", Toast.LENGTH_LONG).show()
            }
        }
    }

    Column(modifier = Modifier.fillMaxWidth()) {
        SecurePaymentStatusView(
            state = statusState,
            modifier = Modifier.fillMaxWidth()
        )

        if (resultVisible) {
            Text(
                text = resultText,
                modifier = Modifier.padding(top = 8.dp)
            )
        }
    }
}