Data validation

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

1. Component creation: Paze must be included in session allowedFundingTypes (SDK0118 if missing).
2. Presentment: Session clientId, currency, client presentation settings, and optional identity fields.
3. Checkout: Amount, billing preferences, shipping countries, cobrand configuration, and identity re-validation.
4. Complete: Transaction type, amount, currency, billing preference, and merchantCategoryCode when the SDK builds the Paze complete request.
5. Merchant callbacks: Optional approval gates after checkout, before decryption, and before authorisation.

If validation fails, the SDK surfaces a BaseSdkException with a structured error code in the SDK12XX range (or SDK0118 at component creation). Authorisation submission failures are surfaced through onSubmitError instead of onError.

By default, the Paze component validates that:

• allowedFundingTypes.wallets.paze.clientId is present in the session.
• merchantCategoryCode is present in the session when the SDK builds the complete request (on iOS).
• The transaction currency is USD.
• clientName is 50 characters or fewer.
• siteName (brand name) is 50 characters or fewer.
• paymentDescription (statement descriptor) is 25 characters or fewer.
• Email addresses are valid RFC 5322 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.
• billingPreference is one of .all, .zipCountry, or .none.
• acceptedShippingCountries use valid ISO 3166-1 alpha-2 codes (exactly two uppercase letters).
• Each cobrand entry has a non-empty cobrandName.

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.

The Paze component returns structured error codes for validation failures:

For the complete list of Paze error codes, including complete-step validation and decode failures, see Full Paze error reference.

config.onError = { error in
    switch error.errorCode {
    case "SDK0118":
        showError("Paze isn't enabled for this session.")
    case "SDK1210":
        showError("Please enter a valid email address.")
    case "SDK1212":
        showError("Please enter a valid US phone number (e.g. 15551234567).")
    case "SDK1213":
        showError("Paze is only available for USD transactions.")
    case "SDK1202":
        showError("Paze client ID is missing from the session.")
    case "SDK1202A":
        showError("Paze merchant category code is missing from the session.")
    case "SDK1214", "SDK1200":
        showError("Paze checkout failed. Please try again.")
    default:
        showError(error.errorMessage)
    }
}

Callbacks that use await must be marked async on PazeButtonComponentConfig:

The iOS component doesn't provide onCustomValidation. Validate cart state, terms acceptance, and inventory in your UI before enabling the Paze button, or run non-blocking checks in onPazeButtonClicked before the Paze web session opens.

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.

config.onCheckoutComplete = { result async in
    guard let decoded = result.checkoutDecodedResponse else { return false }

    let isValid = await validateCheckoutOnBackend(
        sessionId: decoded.sessionId,
        cardLastFour: decoded.maskedCard?.panLastFour,
        cardBrand: decoded.maskedCard?.paymentCardBrand
    )

    return isValid
}

config.onCheckoutIncomplete = { result async in
    showMessage("Payment was not completed. Please try again.")
}

onComplete fires first with securedPayload in completeDecodedResponse. onPreDecryption runs next — return false to skip SDK decryption and handle the payload on your backend.

Use onPreDecryption to control whether the SDK decrypts the secured payload. When omitted, the SDK defaults to decrypting.

config.onPreDecryption = { async in false }

config.onComplete = { result async in
    guard let securedPayload = result.completeDecodedResponse?.securedPayload else { return }
    await sendToBackendForDecryption(securedPayload: 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.

config.onPreAuthorisation = { async in
    if fraudCheckFailed() {
        return .cancel
    }

    return .transactionInitData(PazeTransactionInitData(
        riskScreeningData: RiskScreeningData(
            performRiskScreening: true,
            userIp: await getUserIpAddress()
        )
    ))
}

The table in Built-in validation lists the errors you are most likely to encounter during integration. This section lists every Paze-related error code defined in the iOS SDK (SDK0118 at component creation, SDK1200–SDK1235 during the payment flow).

The SDK always sends transactionType: "PURCHASE" when calling the Paze complete API, regardless of the card intent (.authorisation or .purchase) configured on CheckoutConfig. Card intent applies to the Unity authorisation request after decryption, not to the Paze complete step. See Transaction intents.