# How it works

Learn about PXP's Paze component for Android.

## Overview

Paze is a US digital wallet that lets shoppers pay with cards stored in their Paze wallet. On Android, the Paze component renders a native Paze-branded button, opens the Paze web checkout in a Chrome Custom Tab, and orchestrates checkout completion, token decryption, and transaction submission through PXP.

With the Paze component, you can benefit from:

* **Secure checkout:** Payments use network tokens and cryptograms from the Paze wallet rather than raw card numbers.
* **Reduced friction:** Shoppers authenticate with Paze instead of entering card details manually.
* **Merchant approval gates:** Approve or reject checkout data, decryption, and authorisation at `onCheckoutComplete`, `onPreDecryption`, and `onPreAuthorisation`.
* **Flexible decryption:** Let the SDK decrypt tokens automatically, or handle decryption on your backend.
* **Fraud controls:** Integrate AVS and Kount risk screening through component configuration and callbacks.
* **Brand customisation:** Configure official Paze button colours, shapes, and labels to match your checkout.


Paze currently supports `USD` transactions only. The SDK validates currency during presentment and throws `SDK1213` if another currency is used.

## Presentment

The Paze button uses static presentment: it appears after SDK validation. When you display the component in Compose (`Content()`), the SDK:

1. Validates that `session.allowedFundingTypes.wallets.paze.clientId` is present, enforces length limits on optional `clientName`, `siteName` (SDK config), and `paymentDescription` (component config) when set.
2. Validates optional shopper identity (`emailAddress`, `phoneNumber`) when provided.
3. Confirms the transaction currency is `USD`.
4. Calls `onInit`, shows the Paze button, and calls `onPresentmentResolved` with whether a Custom Tabs-compatible browser is available.


If validation fails, the button stays hidden and `onPresentmentResolved(false)` is called followed by `onError`.

Optional `emailAddress` and `phoneNumber` are forwarded to the Paze create-session request when provided. Each field is validated independently at presentment and again at checkout.

`onPresentmentResolved` reflects Custom Tab availability, not Paze wallet eligibility. When presentment succeeds, the button remains visible whether or not a Custom Tabs-compatible browser is available. Use the callback to show warnings or fallback payment methods before checkout.

Set `transactionData.entryType` to `EntryType.Ecom` when initialising the SDK. Paze expects an e-commerce entry type on the authorisation request. The standalone button doesn't validate entry type at presentment; use `EntryType.Ecom` for Paze checkout flows.

## Payment flow

The Paze payment flow has five steps.

### Step 1: Presentment

The component validates configuration and renders the native Paze button in your Compose UI via `component.Content(modifier)` when presentment succeeds.

### Step 2: Checkout

When the shopper taps the button:

1. The SDK validates checkout configuration (amount, identity, and optional `sessionId` length). If validation fails, `onError` fires and checkout does not start.
2. `onPazeButtonClicked` runs after validation succeeds and before create-session.
3. The SDK calls the PXP `create-session` API and receives a Paze checkout URL.
4. A full-screen Custom Tab opens the Paze web checkout.
5. The shopper completes or abandons checkout; Paze redirects to `pxpcheckout://callback` or `pxpcheckout://paze`.
6. The SDK's merged `PazeSdkRedirectActivity` receives the redirect and forwards it to your host Activity.
7. Your host Activity delivers the result to the component, typically via `onNewIntent` and `deliverPazeCheckoutResult`. The component also checks for pending results when the host Activity resumes.


### Step 3: Merchant validation

If checkout returns `COMPLETE`, `onCheckoutComplete` is called with checkout details including masked card data. Return `false` to reject the checkout; the SDK treats it as incomplete and calls `onCheckoutIncomplete`.

### Step 4: Completion and decryption

If you approve checkout, the SDK calls the PXP Paze `complete` API (using `merchantCategoryCode` from the session) and receives a `securedPayload`. `onComplete` fires with the decoded response before decryption. By default, the SDK decrypts through the PXP `decrypt-token` API. Return `false` from `onPreDecryption` to handle decryption on your backend instead.

### Step 5: Authorisation

After decryption, the SDK builds a scheme-token card transaction and submits it to PXP (calling `onGetShopper` when configured). Use `onPreAuthorisation` to provide risk screening data or abort the flow. `onPostAuthorisation` receives a `MerchantSubmitResult` with `merchantTransactionId` and `systemTransactionId` — verify the full outcome on your backend. Hard submission failures route to `onSubmitError`.

```mermaid
sequenceDiagram
    participant App as Your Android app
    participant SDK as PXP SDK
    participant Tab as Chrome Custom Tab
    participant Paze as Paze checkout
    participant PXP as PXP API

    App->>SDK: Display component (Content)
    SDK-->>App: onInit / onPresentmentResolved
    App->>SDK: Shopper taps button
    SDK->>SDK: Validate checkout config
    SDK-->>App: onPazeButtonClicked
    SDK->>PXP: create-session
    PXP-->>SDK: pazeCheckoutUrl
    SDK->>Tab: Open checkout URL
    Tab->>Paze: Shopper completes checkout
    Paze-->>Tab: Redirect pxpcheckout://callback or pxpcheckout://paze
    Tab-->>App: PazeSdkRedirectActivity forwards to host
    App->>SDK: deliverPazeCheckoutResult
    SDK-->>App: onCheckoutComplete
    alt merchant approves
        SDK->>PXP: complete
        SDK-->>App: onComplete
        SDK-->>App: onPreDecryption
        SDK->>PXP: decrypt-token (unless manual)
        SDK-->>App: onPostDecryption
        SDK-->>App: onPreAuthorisation
        SDK->>PXP: authorise transaction
        alt MerchantSubmitResult received
            SDK-->>App: onPostAuthorisation
        else hard submission failure
            SDK-->>App: onSubmitError
        end
    else merchant rejects or shopper cancels
        SDK-->>App: onCheckoutIncomplete
    end
```

## Supported card networks

Paze supports Visa, Mastercard, and Discover. Configure accepted networks with `acceptedPaymentCardNetworks` on `PazeButtonComponentConfig`. 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. The value is forwarded to the Paze create-session request when set.

## Button customisation

The component renders native Paze button artwork. Configure appearance with `PazeButtonStyleConfig` on `PazeButtonComponentConfig`. When `style` is `null`, defaults are auto colour, default shape, and checkout-with label. See [Configuration](/guides/checkout/components/android/paze/configuration#styling) for the full reference.

| Colour | Description |
|  --- | --- |
| `AUTO` (default) | Adapts to system theme (Paze Blue in light mode, White in dark mode). |
| `PAZE_BLUE` | Paze brand blue background with white label. |
| `WHITE` | White background with Paze blue label. |
| `WHITE_WITH_OUTLINE` | White background with outline border. |
| `MIDNIGHT_BLACK` | Midnight black background with white label. |


| Shape | Description |
|  --- | --- |
| `DEFAULT` (default) | Rounded corners (4 dp radius). |
| `RECTANGLE` | Square corners (0 dp radius). |
| `PILL` | Fully rounded pill shape. |


| Label | Description |
|  --- | --- |
| `CHECKOUT_WITH` (default) | "Check out with Paze" label artwork. |
| `CHECKOUT` | Paze logo only (no label text). |
| `PAZE_CHECKOUT` | "`logo` checkout" compact label artwork. |
| `DONATE_WITH` | "Donate with Paze" label artwork. |


Don't apply `Modifier.background`, tint modifiers, or other styling that overrides official Paze artwork.

## Decryption options

* **SDK-managed decryption (default):** The SDK calls the PXP `decrypt-token` endpoint after `onComplete`. Implement `onPostDecryption` to inspect the decrypted token before authorisation.
* **Manual decryption:** Return `false` from `onPreDecryption` to skip SDK decryption. Use `onComplete` to receive the `securedPayload` and decrypt from your backend. See [Implementation](/guides/checkout/components/android/paze/implementation#backend-decryption).


## Transaction intents

Paze transactions are submitted as scheme-token card payments. Configure `transactionData.entryType` as `EntryType.Ecom` and set the card intent when you initialise the SDK:

| Intent | Description |
|  --- | --- |
| `Authorisation` | Authorise and hold funds for later capture. |
| `Purchase` | Capture payment immediately. |


The SDK forwards any `CardIntentType` set on `transactionData.intent.card`. `Authorisation` and `Purchase` are the intents typically used for Paze checkout.

## Fraud and address verification

* **AVS:** Set `performAVS = true` on `PazeButtonComponentConfig` when a billing address is returned from decryption. AVS is applied only when `performAVS` is explicitly `true`. Set `billingPreference` to `ALL` so Paze collects billing data during checkout.
* **Kount:** Return `PazePreAuthorisationResult.TransactionInitData(...)` from `onPreAuthorisation` with `riskScreeningData`. Set `kountDisabled = true` on `PxpSdkConfig` to disable Kount device fingerprinting.


## What's next?

- **[Implementation](/guides/checkout/components/android/paze/implementation):** Integrate the Paze button, handle redirects, and wire callbacks.
- **[Configuration](/guides/checkout/components/android/paze/configuration):** Explore component properties and styling.
- **[Events](/guides/checkout/components/android/paze/events):** Reference all Paze callbacks and payload types.