Přeskočit na hlavní obsah

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 tyto typy výsledku:

Typ PaymentResultPopis
PaymentResult.PaidPlatba byla dokončena a potvrzena.
PaymentResult.AuthorizedPlatba byla autorizována bankou (předautorizace).
PaymentResult.PendingPlatba se stále zpracovává (mezistav).
PaymentResult.CancelledPlatba byla zrušena nebo zamítnuta serverem.
PaymentResult.FailedChyba na straně knihovny během platebního procesu.

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

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

Authorized​

Platba byla autorizována (předautorizována) bankou. Jde o finální stav. Zachycení (settlement) platby provede obchodník samostatně pomocí standardních endpointů /capturePreauth nebo /cancelPreauth.

is PaymentResult.Authorized -> {
    val transId = result.transId
    // Platba autorizována, čeká na zachycení
}

PENDING​

Platba ještě není finální, backend ji stále zpracovává. Finálním stavem bude Paid, Authorized nebo Cancelled.

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

CANCELLED​

Platba byla zrušena nebo zamítnuta serverem. Obsahuje identifikátor transakce a volitelný důvod.

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

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

Možné hodnoty errorReason​

errorReasonVýznam
CUSTOMER_CLICKZrušeno plátcem.
FRAUD_SUSPECTEDPodezření na podvod.
ESHOP_CANCELLEDZrušeno obchodníkem.
PROVIDER_REPORTZrušeno providerem.
PROVIDER_TIMEOUTVypršel časový limit poskytovatele.
CUSTOMER_TIMEOUTVypršel časový limit platby.
ACS_TIMEOUTVypršel časový limit pro ověření.
INVALID_CARDNO_EXPIRYChybně zadané číslo karty nebo datum platnosti karty.
INVALID_CVCChybně zadaný CVC / CVV kód.
LIMIT_EXCEEDEDLimit karty byl překročen.
NO_FUNDSNa účtu není dostatečný zůstatek.
REJECTED_BY_BANKPlatba byla zamítnuta bankou.
3DS_AUTH_FAILOvěření platby nebylo úspěšné.
NOT_SPECIFIEDNespecifikováno.
Testování chybových scénářů

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

FAILED​

Chyba na straně knihovny, která nastala během 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 — např. 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       // např. "PAYMENT_NETWORK_ERROR"
    val errorMessage = result.error.message // např. "Payment request failed due to a network error"
    // Zobrazení chyby uživateli
}

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ódPopis
DEVICE_ROOTEDZařízení je pravděpodobně rootované nebo jinak pozměněné. Inicializace je zablokovaná za účelem ochrany karetních dat. V devMode se tato kontrola přeskočí.
INIT_NETWORK_ERRORInicializace session selhala kvůli síťové chybě.
INIT_UNAUTHORIZEDServer vrátil HTTP 401 při inicializaci — neplatná nebo expirovaná autorizace.
INIT_FAILEDInicializace session selhala (jiný než síťový důvod).
APPLICATION_NOT_ALLOWEDAplikace není povolena pro použití SDK (package name není na allow-listu).
Zpracování platby​
KódPopis
SESSION_NOT_INITIALIZEDSession nebyla inicializována. Zavolejte nejprve initialize().
INVALID_CARD_DATAKaretní data nejsou validní.
MISSING_CARDHOLDER_NAMEJméno držitele karty nebylo poskytnuto.
PAYMENT_FAILEDPlatba selhala (jiný než síťový důvod).
PAYMENT_NETWORK_ERRORPlatební požadavek selhal kvůli síťové chybě.
PAYMENT_CREATE_FAILEDVytvoření platby selhalo.
POLLING_TIMEOUTKontrola stavu platby vypršela.
POLLING_NETWORK_ERRORKontrola stavu platby selhala kvůli síťové chybě.
Google Pay​
KódPopis
GOOGLE_PAY_NOT_CONFIGUREDGoogle Pay není nakonfigurován.
GOOGLE_PAY_FAILEDGoogle Pay platba selhala.
Validace polí​
KódPopis
INVALID_PANNeplatné číslo karty.
INVALID_EXPIRY_MONTHNeplatný měsíc expirace.
CARD_EXPIREDKarta je expirovaná.
INVALID_CVVNeplatný CVV kód.

SecurePaymentStatusView​

Komponenta SecurePaymentStatusView slouží k zobrazování stavových hlášek platby (úspěch, zpracování, 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)
PaymentResultChování
PaidZobrazí lokalizovanou zprávu „Paid" se zeleným stylem (úspěch).
AuthorizedZobrazí lokalizovanou zprávu „Authorized" se zeleným stylem (úspěch).
PendingZobrazí lokalizovanou zprávu „Processing" s oranžovým stylem (zpracování).
CancelledZobrazí errorReason s červeným stylem (chyba).
FailedZobrazí error.message s červeným stylem (chyba).

Skrytí view​

statusState.clear()

Stylizace​

Podrobnosti o stylizaci SecurePaymentStatusView prostřednictvím update bloku, setter metod a XML atributů naleznete v sekci Stylizace komponent.

Kompletní příklad zpracování 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čítko — viz sekce Karetní data)

    // Zpracování 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 autorizována\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šena: ${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)
            )
        }
    }
}