Data validation

The Paze component validates configuration, identity data, and transaction parameters before and during the payment flow. Validation runs at multiple stages:

1. Presentment: Session clientId, currency, client presentation settings, and optional identity fields when the component Content() is composed.
2. Checkout: Identity re-validation, amount check, optional sessionId length, and create-session request building.
3. Complete: merchantCategoryCode and complete-request fields when the SDK calls Paze complete.
4. Merchant callbacks: Optional approval gates via onCheckoutComplete, onPreDecryption, and onPreAuthorisation.

If validation fails, the SDK surfaces a BaseSdkException with a structured error code in the SDK12XX range. Most validation, checkout, and decrypt failures route to onError. Authorisation submission failures route to onSubmitError.

The SDK validates session configuration, presentation settings, and optional identity fields before checkout proceeds. By default, the Paze component checks that:

• allowedFundingTypes.wallets.paze.clientId is present in the session.
• merchantCategoryCode is present in the session when the SDK builds the complete request.
• The transaction currency is USD.
• When set, clientName is 50 characters or fewer.
• When set, siteName (brand name) is 50 characters or fewer.
• When set, paymentDescription (statement descriptor) is 25 characters or fewer at presentment.
• Email addresses are valid RFC 5322-style format and 128 characters or fewer when provided (at presentment and again at checkout).
• Phone numbers match 1 followed by 10 digits when provided (at presentment and again at checkout).
• The transaction amount is greater than 0 at checkout.
• sessionId is 255 characters or fewer when set on the component config.

The button uses static presentment: it appears after presentment validation succeeds when Content() is composed. Optional emailAddress and phoneNumber are validated when provided and forwarded to the Paze create-session request. Both fields are optional but recommended when you have verified shopper identity.

acceptedPaymentCardNetworks, cobrand, and acceptedShippingCountries are forwarded to create-session when set. For card networks, omitting the property, passing an empty list, or selecting all three supported networks (VISA, MASTERCARD, DISCOVER) sends no network filter to Paze.

Set transactionData.entryType to EntryType.Ecom when initialising the SDK. Paze expects an e-commerce entry type on the authorisation request. The standalone Paze button component does not validate entryType at presentment — it is included on the transaction request after decryption. Checkout drop-in validates EntryType.Ecom separately (SDK1124).

Component identity (emailAddress / phoneNumber) is passed to Paze during session creation when provided. Each field is validated independently when set. Identity is separate from onGetShopper, which supplies shopper data for Unity authorisation after decryption.

When you set one or both identity fields, the SDK sends them to Paze as follows:

The Paze component returns structured error codes when built-in validation or flow checks fail:

Use onError to map SDK validation and flow errors to user-facing messages:

config.onError = { error ->
    when (error.errorCode) {
        "SDK1210" -> showError("Please enter a valid email address.")
        "SDK1212" -> showError("Please enter a valid US phone number (e.g. 15551234567).")
        "SDK1213" -> showError("Paze is only available for USD transactions.")
        "SDK1202", "SDK1202A" -> showError("Paze is not configured for this session.")
        "SDK1231" -> showError("Invalid shipping country configuration.")
        "SDK1232" -> showError("Cobrand configuration is incomplete.")
        "SDK1233" -> showError("Payment token could not be processed. Please try again.")
        "SDK1200", "SDK1214" -> showError("Paze checkout failed. Please try again.")
        else -> showError(error.message ?: "Payment could not be completed.")
    }
}

Beyond built-in SDK checks, you can add merchant-side approval gates at key points in the flow.

Validate cart state, terms acceptance, and inventory before checkout by disabling the Paze button in your UI until pre-requisites are met. onPazeButtonClicked has no return value and can't cancel the flow; the SDK opens the Custom Tab as soon as the callback completes. Use onPazeButtonClicked only for non-blocking side effects such as analytics or clearing error messages.

To hard-block checkout after the shopper returns from Paze, return false from onCheckoutComplete.

Use onCheckoutComplete to inspect checkout data and approve or reject before the SDK calls complete. Return false to treat the checkout as incomplete.

The following example approves checkout only after server-side validation succeeds:

config.onCheckoutComplete = { result ->
    val decoded = result.checkoutDecodedResponse ?: return@onCheckoutComplete false
    return@onCheckoutComplete validateCheckoutOnBackend(
        sessionId = decoded.sessionId,
        cardLastFour = decoded.maskedCard.panLastFour,
    )
}

config.onCheckoutIncomplete = { _ ->
    showMessage("Payment was not completed. Please try again.")
}

Use onPreDecryption to control whether the SDK decrypts the secured payload. Return false to handle decryption on your backend. When omitted, the SDK defaults to decrypting.

Return false from onPreDecryption and send the secured payload to your backend in onComplete:

config.onPreDecryption = { false }

config.onComplete = { result ->
    val securedPayload = result.completeDecodedResponse?.securedPayload ?: return@onComplete
    sendToBackendForDecryption(securedPayload)
}

Use onPreAuthorisation to provide risk screening data or abort the transaction before submission. When you return TransactionInitData(...) with riskScreeningData, the SDK validates the Kount payload before submitting the transaction. Invalid risk screening data throws a ValidationException surfaced through onSubmitError.

The following example cancels authorisation when a fraud check fails, or passes Kount risk screening data when it passes:

config.onPreAuthorisation = {
    if (fraudCheckFailed()) {
        PazePreAuthorisationResult.Cancel
    } else {
        PazePreAuthorisationResult.TransactionInitData(
            PazeTransactionInitData(
                riskScreeningData = RiskScreeningData(
                    performRiskScreening = true,
                    userIp = getUserIpAddress(),
                ),
            ),
        )
    }
}

The SDK applies the following rules to optional emailAddress and phoneNumber fields on the component config.

Email validation runs at presentment and again at checkout when the field is set:

Phone validation runs at presentment and again at checkout when the field is set: