# 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:

```kotlin
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`:

```kotlin
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](#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 aren't read by the standalone Paze button component. Don't set them when integrating the component directly.

## Styling

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

```kotlin
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:

```kotlin
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](/guides/checkout/components/android/paze/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.

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

See [Compliance](/guides/checkout/components/android/paze/compliance#address-verification-avs) 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:

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

Pass Kount risk screening data at authorisation through `onPreAuthorisation` and `PazePreAuthorisationResult.TransactionInitData(...)`. See [Events](/guides/checkout/components/android/paze/events#onpreauthorisation) and [Compliance](/guides/checkout/components/android/paze/compliance#kount-risk-screening).

## Event handling

Register callbacks on `PazeButtonComponentConfig` to hook into the checkout lifecycle:

```kotlin
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](/guides/checkout/components/android/paze/events).

When `onPreDecryption` returns `false` (merchant-managed decryption), the SDK skips decrypt and authorisation. Don't wire `onPostDecryption`, `onPreAuthorisation`, `onPostAuthorisation`, or `onSubmitError` on that path — use `onComplete` to receive the `securedPayload` instead. See [Implementation](/guides/checkout/components/android/paze/implementation#backend-decryption).

## Displaying the component

Render the Paze button in your Compose hierarchy:

```kotlin
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](/guides/checkout/components/android/paze/implementation#step-2-handle-checkout-redirects).

## Examples

### Donation flow

Use the `DONATE_WITH` label and a short statement descriptor:

```kotlin
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:

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