# How it works

Learn about PXP's Paze component for Web.

## Overview

Paze is a US digital wallet that lets shoppers pay with cards stored in their Paze wallet. The Paze component loads the native Paze Digital Wallet SDK, renders an official `<paze-button>` element, and orchestrates checkout, 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.
* **Dynamic presentment:** Show the button only when Paze determines the shopper is eligible, or always display it in static mode.
* **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 component initialisation and throws `SDK1213` if another currency is used.

## Presentment modes

The component supports two presentment modes through `buttonRenderMode`:

| Mode | Behaviour | Identity requirements |
|  --- | --- | --- |
| `static` (default) | Always shows the Paze button after SDK initialisation. | `emailAddress` and/or `phoneNumber` are optional but validated when provided. |
| `dynamic` | Calls Paze's `canCheckout()` to check shopper eligibility before showing the button. | Both `emailAddress` and `phoneNumber` are required for `canCheckout()`. | At `checkout()`, if both are set, only `phoneNumber` is sent to Paze (email is omitted). |


When presentment resolves, the component calls `onPresentmentResolved(isVisible)` so you can track whether the button is shown.

## Payment flow

The Paze payment flow has five steps.

### Step 1: Presentment

When the component mounts, the SDK:

1. Validates session configuration (including `allowedFundingTypes.wallets.paze.clientId`).
2. Loads the Paze Digital Wallet SDK script from Paze's CDN.
3. Initialises the SDK with your `clientId`, optional `profileId`, and merchant branding.
4. Resolves presentment (static or dynamic) and renders the button.


### Step 2: Checkout

When the shopper clicks the button:

1. Optional `onCustomValidation` runs. Return `false` to prevent checkout.
2. The SDK calls Paze's `checkout()` with transaction amount, currency, billing preferences, and identity data.
3. The shopper completes or abandons the Paze wallet experience.


### Step 3: Merchant validation

If checkout returns `COMPLETE`, `onCheckoutComplete` is called with checkout details including card and billing 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 Paze's `complete()` and receives a `securedPayload`. By default, the SDK decrypts this 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. Use `onPreAuthorisation` to provide risk screening data or abort the flow. `onPostAuthorisation` receives the transaction result.

```mermaid
sequenceDiagram
    participant Merchant as Your checkout
    participant SDK as PXP SDK
    participant Paze as Paze wallet
    participant PXP as PXP API

    Merchant->>SDK: Mount paze-button
    SDK->>Paze: Load and initialise SDK
    alt dynamic presentment
        SDK->>Paze: canCheckout(email, phone)
        Paze-->>SDK: consumerPresent
    end
    SDK-->>Merchant: onPresentmentResolved
    Merchant->>SDK: Shopper clicks button
    SDK->>Paze: checkout()
    Paze-->>SDK: checkout result
    SDK-->>Merchant: onCheckoutComplete
    alt merchant approves
        SDK->>Paze: complete()
        Paze-->>SDK: securedPayload
        SDK-->>Merchant: onComplete
        SDK->>PXP: decrypt-token (unless manual)
        SDK-->>Merchant: onPostDecryption
        SDK->>PXP: transaction
        SDK-->>Merchant: onPostAuthorisation
    else merchant rejects
        SDK-->>Merchant: onCheckoutIncomplete
    end
```

## Supported card networks

By default, the component accepts all Paze-supported networks:

- Visa (`VISA`)
- Mastercard (`MASTERCARD`)
- Discover (`DISCOVER`)


Use `acceptedPaymentCardNetworks` to restrict which networks appear in the Paze wallet.

## Button customisation

The component renders Paze's native `<paze-button>` web component with configurable styling:

### Colours

| Value | Description |
|  --- | --- |
| `white` | White background. |
| `whitewithoutline` | White background with outline. |
| `midnightblack` | Dark background. |
| `pazeblue` | Paze brand blue (recommended). |


### Shapes

| Value | Description |
|  --- | --- |
| `default` | Paze default corner radius. |
| `rectangle` | Rectangular button. |
| `pill` | Fully rounded ends. |


### Labels

| Value | Description |
|  --- | --- |
| `checkout` | "Paze checkout". |
| `check out with` | "Checkout with Paze". |
| `Donate with` | "Donate with Paze". |


Set `disableMaxHeight: true` in the style object to let the button fill its container height.

## Decryption options

The component supports two decryption approaches:

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


## Transaction intents

Paze transactions are submitted as scheme token card payments with `walletType: "Paze"`. The card intent from your session configuration determines the transaction flow:

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


Configure the intent in your session's `transactionMethod.intent.card` value and mirror it in `transactionData.intent.card` during SDK initialisation.

## Fraud and address verification

* **AVS:** Set `performAVS: true` to include billing address from the decrypted payload in the transaction request when the **SDK submits the transaction**. Requires `billingPreference: "ALL"` so Paze returns a billing address. If you use manual backend decryption, apply AVS fields on your own transaction request instead.
* **Kount:** Pass risk screening data through `onPreAuthorisation`. Set `kountDisabled: true` on SDK initialisation to disable Kount device fingerprinting.


## What's next?

- **[Onboarding](/guides/checkout/components/web/paze/onboarding):** Configure Paze in the Unity Portal.
- **[Implementation](/guides/checkout/components/web/paze/implementation):** Step-by-step integration guide.
- **[Configuration](/guides/checkout/components/web/paze/configuration):** Component configuration options.
- **[Events](/guides/checkout/components/web/paze/events):** Callback reference and event data structures.