Configuration

Learn about how to configure the Paze button component for Android.

Basic usage

Minimal configuration

At minimum, the Paze button requires a session with Paze enabled (allowedFundingTypes.wallets.paze.clientId), USD transaction data, and merchantCategoryCode in the session for the complete step. Component configuration can be as simple as:

val config = PazeButtonComponentConfig().apply {
    emailAddress = "customer@example.com"
}

val pazeButton = checkout.createComponent<PazeButtonComponent>(
    ComponentType.PAZE_BUTTON,
    config
)

The minimal component config supports these optional identity properties:

Property	Description
`emailAddress` String?	Optional shopper email. Validated when provided (max 128 characters, RFC 5322-style format). Forwarded to the Paze create-session request when set.
`phoneNumber` String?	Optional US phone number: 11 digits starting with `1`, without the `+` prefix (e.g. `15551234567`). Forwarded to create-session when set.

Optional emailAddress and phoneNumber are recommended when you have verified shopper identity — Paze uses them during checkout. Each field is validated independently when set.

After presentment validation succeeds, the button is shown when you render Content(). Optional emailAddress and phoneNumber are forwarded to the Paze create-session request when provided. Include merchantCategoryCode in allowedFundingTypes.wallets.paze in the session for the complete step.

The SDK opens Paze checkout in a Chrome Custom Tab and decrypts tokens by default. Implement onGetShopper on PxpSdkConfig to supply shopper data during authorisation.

Advanced configuration

The following example shows common optional properties and lifecycle callbacks on PazeButtonComponentConfig:

val config = PazeButtonComponentConfig().apply {
    emailAddress = "customer@example.com"
    phoneNumber = "15551234567"
    paymentDescription = "Order #12345"
    billingPreference = PazeBillingPreference.ALL
    acceptedPaymentCardNetworks = listOf(
        PazeAcceptedPaymentCardNetwork.VISA,
        PazeAcceptedPaymentCardNetwork.MASTERCARD,
    )
    cobrand = listOf(PazeCobrandConfig(cobrandName = "Rewards Plus", benefitsOffered = true))
    performAVS = true
    style = PazeButtonStyleConfig(
        color = PazeButtonColor.PAZE_BLUE,
        shape = PazeButtonShape.PILL,
        label = PazeButtonLabel.CHECKOUT_WITH,
    )

    onInit = { Log.d("Paze", "Initialised") }
    onPresentmentResolved = { customTabAvailable -> Log.d("Paze", "Custom Tab available: $customTabAvailable") }
    onCheckoutComplete = { _ -> true }
    onPreDecryption = { true }
    onPostDecryption = { payload -> Log.d("Paze", payload.fundingData.cardNetwork) }
    onPostAuthorisation = { result ->
        Log.d("Paze", result.systemTransactionId)
    }
}

val pazeButton = checkout.createComponent<PazeButtonComponent>(ComponentType.PAZE_BUTTON, config)

The following table describes optional properties on PazeButtonComponentConfig:

Property	Description
`emailAddress` String?	Optional shopper email. Validated at presentment and checkout when provided. Forwarded to create-session when set.
`phoneNumber` String?	Optional US phone: 11 digits starting with `1`, without `+`. Validated at presentment and checkout when provided. Forwarded to create-session when set.
`paymentDescription` String?	Optional statement descriptor. Maximum 25 characters. Validated during presentment.
`billingPreference` PazeBillingPreference?	Billing address collection in the Paze checkout. When `null`, the SDK defaults to `ALL` for create-session; the complete request sends the configured value only when set. Possible values: `ALL` `ZIP_COUNTRY` `NONE`
`sessionId` String?	Optional session ID echoed back by Paze. Falls back to the SDK session ID when not set. Validated at checkout when provided (max 255 characters).
`acceptedShippingCountries` List<String>?	The list of accepted shipping countries, in ISO 3166-1 alpha-2 format. Forwarded to create-session when set.
`acceptedPaymentCardNetworks` List<PazeAcceptedPaymentCardNetwork>?	The list of accepted card networks. When omitted, empty, or when all three supported networks are explicitly selected, Paze receives no network filter and all supported networks are accepted. Subsets restrict eligible cards. Forwarded to create-session when set. Possible values: `VISA` `MASTERCARD` `DISCOVER`
`cobrand` List<PazeCobrandConfig>?	Optional cobrand entries for eligible card display in the Paze wallet. Each entry requires a `cobrandName`. Forwarded to create-session when set.
`style` PazeButtonStyleConfig?	Official Paze button styling. When `null`, default Paze button styling is used. See Styling.
`performAVS` Boolean?	When explicitly `true`, includes billing address from the decrypted payload in AVS fields when the SDK submits the transaction. `null` or `false` disables AVS. Set `billingPreference` to `ALL` when using AVS.

Your merchant branding (clientName, siteName) is configured on PxpSdkConfig. Both are optional; the SDK validates length when set. clientName maps to Paze's name (max 50 characters) and siteName maps to brandName (max 50 characters).

PazeButtonComponentConfig also exposes confirmLaunch and enhancedTransactionData. These properties are reserved for checkout drop-in integration and are not read by the standalone Paze button component. Do not set them when integrating the component directly.

Styling

The component renders native Paze button artwork. Configure official attributes with PazeButtonStyleConfig:

config.style = PazeButtonStyleConfig(
    color = PazeButtonColor.PAZE_BLUE,
    shape = PazeButtonShape.PILL,
    label = PazeButtonLabel.CHECKOUT_WITH,
)

Supported PazeButtonStyleConfig properties:

Property	Description
`color` PazeButtonColor	The button colour theme. `AUTO` (default) adapts to the system theme: Paze Blue in light mode, White in dark mode. Possible values: `AUTO` (default) `PAZE_BLUE` `WHITE` `WHITE_WITH_OUTLINE` `MIDNIGHT_BLACK`
`shape` PazeButtonShape	The button shape. Possible values: `DEFAULT` (default, 4 dp corner radius) `RECTANGLE` (0 dp, square corners) `PILL` (fully rounded)
`label` PazeButtonLabel	The button label artwork. Default is `CHECKOUT_WITH`. Possible values: `CHECKOUT_WITH` (default) `CHECKOUT` `PAZE_CHECKOUT` `DONATE_WITH`

Update the button style at runtime:

pazeButton.updateConfig(pazeButton.config.apply {
    style = PazeButtonStyleConfig(color = PazeButtonColor.WHITE, shape = PazeButtonShape.PILL)
})

Don't override the Paze button with custom Compose modifiers that alter its appearance. For example Modifier.background, tint modifiers, or colour overrides on the button Composable. Use only the supported style values to remain compliant with Paze branding guidelines. See Compliance.

Address verification (performAVS)

When performAVS is explicitly true, the SDK adds billing address data from the decrypted Paze payload to the addressVerification field of the transaction request when available. Set billingPreference to ALL so the Paze wallet collects and returns a billing address during checkout.

val config = PazeButtonComponentConfig().apply {
    performAVS = true
    billingPreference = PazeBillingPreference.ALL
}

See Compliance for backend decryption and AVS considerations.

Kount device fingerprinting

Kount device fingerprinting is enabled by default on PxpSdkConfig. Disable it only when your fraud strategy does not require device-risk data — for example during local testing:

val sdkConfig = PxpSdkConfig(
    kountDisabled = true,
    // ...
)

Pass Kount risk screening data at authorisation through onPreAuthorisation and PazePreAuthorisationResult.TransactionInitData(...). See Events and Compliance.

Event handling

config.onInit = { }
config.onPresentmentResolved = { customTabAvailable -> }
config.onPazeButtonClicked = { }
config.onCheckoutComplete = { result -> true }
config.onCheckoutIncomplete = { result -> }
config.onComplete = { result -> }
config.onPreDecryption = { true }
config.onPostDecryption = { decryptedPayload -> }
config.onPreAuthorisation = { PazePreAuthorisationResult.Proceed }
config.onPostAuthorisation = { result -> }
config.onSubmitError = { submitError -> }
config.onError = { error -> }

The following table summarises each callback:

Callback	Description
`onInit` () -> Unit	Called after presentment validation succeeds, when `Content()` is composed.
`onPresentmentResolved` (Boolean) -> Unit	When presentment succeeds, called with whether a Custom Tabs–compatible browser is available (the button remains visible either way). When presentment validation fails, the button is hidden and this callback receives `false` (see `onError`).
`onPazeButtonClicked` suspend () -> Unit	Called when the button is tapped, after checkout validation and before the Custom Tab opens. Use for analytics or UI updates only — there is no return value. To block checkout before the tab opens, disable the button in your UI until prerequisites are met.
`onCheckoutComplete` suspend (PazeCheckoutResult) -> Boolean	Called when checkout returns `COMPLETE`. Return `true` to proceed, or `false` to cancel. Defaults to `true` when omitted.
`onCheckoutIncomplete` suspend (PazeCheckoutResult) -> Unit	Called when checkout ends without completion, the shopper cancels, or you return `false` from `onCheckoutComplete`.
`onComplete` suspend (PazeCompleteResult) -> Unit	Called when the complete response is decoded, before decryption and authorisation.
`onPreDecryption` suspend () -> Boolean	Called after `onComplete`, before SDK decryption. Defaults to `true` when omitted.
`onPostDecryption` suspend (PazeDecryptTokenResponseSuccess) -> Unit	Called after the SDK decrypts the secured payload. Skipped when `onPreDecryption` returns `false`.
`onPreAuthorisation` suspend () -> PazePreAuthorisationResult	Called before transaction submission. Return `Proceed`, `Cancel`, or `TransactionInitData(...)`. Defaults to `Proceed` when omitted.
`onPostAuthorisation` suspend (MerchantSubmitResult) -> Unit	Called when the SDK receives a `MerchantSubmitResult` with `merchantTransactionId` and `systemTransactionId`. Only invoked when this callback is registered on the config. Verify the transaction outcome on your backend.
`onSubmitError` suspend (BaseSubmitResult) -> Unit	Called when authorisation submission fails. Cast to `FailedSubmitResult` for error details.
`onError` (BaseSdkException) -> Unit	Called on presentment, checkout, complete, or decryption errors. Shopper cancellation uses `onCheckoutIncomplete`.

For detailed callback payloads and event data structures, see Events.

When onPreDecryption returns false (merchant-managed decryption), the SDK skips decrypt and authorisation. Do not wire onPostDecryption, onPreAuthorisation, onPostAuthorisation, or onSubmitError on that path — use onComplete to receive the securedPayload instead. See Implementation.

Displaying the component

Render the Paze button in your Compose hierarchy:

pazeButton.Content(modifier = Modifier.fillMaxWidth())

Presentment runs automatically when you render Content() with a valid Context. Handle checkout redirects in your host Activity — see Implementation.

Examples

Donation flow

Use the DONATE_WITH label and a short statement descriptor:

config.style = PazeButtonStyleConfig(
    color = PazeButtonColor.MIDNIGHT_BLACK,
    shape = PazeButtonShape.DEFAULT,
    label = PazeButtonLabel.DONATE_WITH,
)
config.paymentDescription = "Charity donation"

Enterprise payment with fraud detection

Enable billing collection, AVS, and Kount risk screening before authorisation:

val config = PazeButtonComponentConfig().apply {
    billingPreference = PazeBillingPreference.ALL
    performAVS = true
    onPreAuthorisation = {
        PazePreAuthorisationResult.TransactionInitData(
            PazeTransactionInitData(riskScreeningData = buildRiskScreeningData()),
        )
    }
    onPostAuthorisation = { result ->
        verifyPaymentOnBackend(systemTransactionId = result.systemTransactionId)
    }
}