Override SDK Screens

This guide shows how to replace the appearance of an SDK screen while preserving its behavior (Level 3 — see Customization model).

How it works

You provide the UI (a Composable); the SDK provides the current ViewState (the data and state to present) and the onEvent channel (to report user interactions back to the SDK). The SDK builds its own default screen from those same artifacts, so your screen reproduces the correct presentation and returns the required interactions.

interface SdkRoute
interface SdkRouteContract<S : ViewState, E : ViewEvent> : SdkRoute
typealias OverrideScreenTyped<S, E> = @Composable (viewState: S, onEvent: (E) -> Unit) -> Unit

Routes without a typed contract (such as the internal warm-up loading screen) cannot be overridden. Overrides are registered in SdkUiNavigationConfig.overrideScreens.

Override a screen

import com.pagonxt.sdk.brazil.uxal.navigation.BrSdkRoutes
import com.pagonxt.sdk.core.uxal.navigation.SdkUiNavigationConfig
import com.pagonxt.sdk.core.uxal.navigation.overrideScreen

val config = SdkUiNavigationConfig(
    overrideScreens = mapOf(
        overrideScreen(BrSdkRoutes.Amount) { viewState, onEvent ->
            CustomAmountScreen(
                amountFormatted = viewState.amountFormatted,
                onAmountChanged = { onEvent(BrAmountViewEvent.OnAmountChanged(it)) },
                onConfirm = { onEvent(BrAmountViewEvent.OnContinueClicked) },
            )
        }
    )
)

ApoloSdk.Builder(applicationContext)
    // ...
    .customizeNavigationConfig(config)
    .build()

You can override several screens in the same configuration, and apply it at build or at runtime with Apolo.customizeNavigation(config) (see Insert screens with Slots).

Overridable routes

Route	Screen	`ViewState`	`ViewEvent`
`Amount`	Amount entry	`BrAmountViewState`	`BrAmountViewEvent`
`ProductSelection`	Method selection (credit/debit/voucher/Pix)	`BrProductSelectionViewState`	`BrProductSelectionViewEvent`
`InstallmentSelection`	Installment selection	`BrInstallmentSelectionViewState`	`BrInstallmentSelectionViewEvent`
`CardReading`	EMV reading / “insert, tap, or swipe” prompt	`BrCardReadingViewState`	`BrCardReadingViewEvent`
`CardSelection`	Application selection (multi-app EMV)	`BrCardSelectionViewState`	`BrCardSelectionViewEvent`
`Processing`	Authorization in progress	`BrProcessingViewState`	—
`PaymentSuccess`	Card sale success	`BrPaymentSuccessViewState`	`BrPaymentSuccessViewEvent`
`PaymentError`	Card sale error	`BrPaymentErrorViewState`	`BrPaymentErrorViewEvent`
`PixQrCodeLoading`	Pix QR loading	`PixQrCodeLoadingViewState`	`PixQrCodeLoadingViewEvent`
`PixQrCode`	QR Code display	`PixQrCodeViewState`	`PixQrCodeViewEvent`
`PixPaymentRecognition`	Recognition (30s window)	`PixPaymentRecognitionViewState`	`PixPaymentRecognitionViewEvent`
`PixPaymentVerification`	Final verification (10s window)	`PixPaymentVerificationViewState`	`PixPaymentVerificationViewEvent`
`PixPaymentSuccess`	Pix success	`PixPaymentSuccessViewState`	`PixPaymentSuccessViewEvent`
`PixPaymentError`	Pix error	`PixPaymentErrorViewState`	`PixPaymentErrorViewEvent`
`CancelInput`	Refund entry	`BrCancelInputViewState`	`BrCancelInputViewEvent`
`SearchTransaction`	Lookup of the transaction to refund	`BrSearchTransactionViewState`	`BrSearchTransactionViewEvent`
`CancelPayment`	Refund confirmation	`BrCancelPaymentViewState`	`BrCancelPaymentViewEvent`
`CancelPaymentProcessing`	Refund processing	`BrCancelPaymentProcessingViewState`	—
`CancelPaymentSuccess`	Refund success	`BrCancelPaymentSuccessViewState`	`BrCancelPaymentSuccessViewEvent`
`CancelPaymentError`	Refund error	`BrCancelPaymentErrorViewState`	`BrCancelPaymentErrorViewEvent`

Next steps

Customize receipts — replace the printed receipt layout.