# Configuration

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

## Basic usage

### Minimal configuration

At minimum, the Paze button component requires a session with Paze enabled and USD transaction data on SDK initialisation. Component configuration can be as simple as:

```typescript
const pazeButton = pxpSdk.create('paze-button', {
  buttonRenderMode: 'static',
  emailAddress: 'customer@example.com'
});
```

| Property  | Description  |
|  --- | --- |
| `buttonRenderMode`enum | Controls presentment. Defaults to `"static"`.Possible values:`"static"`: always show the button after SDK initialisation`"dynamic"`: call Paze's `canCheckout()` to determine eligibility |
| `emailAddress`string | The shopper's email address. Required for dynamic presentment. Validated as RFC 5322 when provided. |
| `phoneNumber`string | US phone number in E.164 format without `+` (e.g., `15551234567`). Required for dynamic presentment. |


When both `emailAddress` and `phoneNumber` are set, the SDK passes both to `canCheckout()` in dynamic mode, but sends only `phoneNumber` to Paze `checkout()`.

The SDK loads the Paze Digital Wallet SDK, handles wallet presentment, and by default decrypts tokens and submits transactions. We also recommend implementing `onGetShopper` on `PxpCheckout.initialize()` to supply shopper data when the SDK submits the transaction.

### Advanced configuration

```typescript
const pazeButton = pxpSdk.create('paze-button', {
  buttonRenderMode: 'dynamic',
  emailAddress: 'customer@example.com',
  phoneNumber: '15551234567',
  paymentDescription: 'Order #12345',
  billingPreference: 'ALL',
  acceptedPaymentCardNetworks: ['VISA', 'MASTERCARD'],
  cobrand: [{ cobrandName: 'Rewards Plus', benefitsOffered: true }],
  performAVS: true,
  style: {
    color: 'pazeblue',
    shape: 'pill',
    label: 'check out with'
  },
  onInit: () => console.log('Paze initialised'),
  onPresentmentResolved: (isVisible) => console.log('Button visible:', isVisible),
  onCheckoutComplete: async (result) => true,
  onPreDecryption: async () => true,
  onPostDecryption: async (payload) => console.log(payload.fundingData.cardNetwork),
  onPostAuthorisation: async (data) => console.log(data.systemTransactionId)
});
```

| Property | Description |
|  --- | --- |
| `buttonRenderMode`enum | Controls button presentment. Defaults to `"static"`.Possible values:`"static"``"dynamic"` |
| `emailAddress`string | The shopper's email for identity and presentment. Required when `buttonRenderMode` is `"dynamic"`. If both email and phone are set, only phone is sent to Paze `checkout()`. |
| `phoneNumber`string | A phone number in US E.164 format without `+`. Required when `buttonRenderMode` is `"dynamic"`. Takes precedence over `emailAddress` at checkout when both are set. |
| `paymentDescription`string | A statement descriptor forwarded to Paze. Maximum 25 characters. |
| `billingPreference`enum | Billing address collection in the Paze popup. Defaults to `"ALL"`.Possible values:`"ALL"``"ZIP_COUNTRY"``"NONE"` |
| `confirmLaunch`boolean | When `true`, Paze may show a confirmation popup before checkout. |
| `sessionId`string | Optional session ID echoed back by Paze. Defaults to the SDK session ID. |
| `acceptedShippingCountries`string[] | The list of accepted shipping countries, in ISO 3166-1 alpha-2 format. |
| `acceptedPaymentCardNetworks`string[] | Accepted card networks. Defaults to `VISA`, `MASTERCARD`, and `DISCOVER`. |
| `cobrand`PazeCobrandConfig[] | Optional cobrand entries for partner branding in the Paze wallet. |
| `enhancedTransactionData`object | Optional checkout metadata forwarded to Paze. See [Enhanced transaction data](#enhanced-transaction-data). |
| `style`PazeButtonStyleConfig | Official Paze button styling. See [Styling](#styling). |
| `performAVS`boolean | When `true`, includes billing address from decrypted payload in AVS fields when the SDK submits the transaction. Defaults to `false`. For manual backend decryption, apply AVS on your transaction request instead. |
| `onCustomValidation`() => Promise<boolean> | Called before checkout opens. Return `false` to prevent checkout. |


Your merchant branding (`clientName`, `siteName`) is configured on `PxpCheckout.initialize()`, not on the button component. `clientName` maps to Paze's `name` (max 50 characters) and `siteName` maps to `brandName` (max 50 characters).

## Enhanced transaction data

`enhancedTransactionData` is optional metadata forwarded to Paze during `checkout()` and `complete()`. Use it when Paze or your merchant agreement requires additional order context.

```typescript
const pazeButton = pxpSdk.create('paze-button', {
  enhancedTransactionData: {
    ecomData: {
      cartContainsGiftCard: false,
      orderForPickup: false,
      orderQuantity: '2',
      orderHighestCost: '49.99',
      finalShippingAddress: {
        line1: '123 Main St',
        city: 'New York',
        state: 'NY',
        zip: '10001',
        countryCode: 'US'
      }
    },
    processingNetwork: ['VISA', 'MASTERCARD']
  }
});
```

| Property | Description |
|  --- | --- |
| `ecomData.cartContainsGiftCard`boolean | Whether the cart contains a gift card. |
| `ecomData.orderForPickup`boolean | Whether the order is for in-store or curbside pickup. |
| `ecomData.orderQuantity`string | Order item count as a string. |
| `ecomData.orderHighestCost`string | Highest line-item cost as a string. |
| `ecomData.finalShippingAddress`object | Shipping address with `line1`, `city`, `state`, `zip`, `countryCode`, and optional `line2` and `name`. |
| `processingNetwork`string[] | Preferred card networks for processing (`VISA`, `MASTERCARD`, or `DISCOVER`). |


## Styling

The component renders Paze's native `<paze-button>` web component. Use the `style` object to configure official Paze button attributes:

```typescript
const config = {
  style: {
    color: 'pazeblue',
    shape: 'pill',
    label: 'check out with',
    disableMaxHeight: false
  }
};
```

| Property | Description |
|  --- | --- |
| `color`enum | The button colour theme.Possible values:`white``whitewithoutline``midnightblack``pazeblue` |
| `shape`enum | The button shape.Possible values:`default``rectangle``pill`

---

- `label`enum
- The button label text.Possible values:`checkout``check out with``Donate with`



---

- `disableMaxHeight`boolean
- When `true`, disables the native max-height so the button fills its container.

 |


Don't apply custom CSS to override the Paze button appearance. Use only the supported `style` values to remain compliant with Paze branding guidelines. See [Compliance](/guides/checkout/components/web/paze/compliance).

## Event handling

```typescript
const config = {
  onInit: () => { },
  onPresentmentResolved: (isVisible) => { },
  onPazeButtonClicked: (event) => { },
  onCheckoutComplete: async (result) => true,
  onCheckoutIncomplete: async (result) => { },
  onComplete: async (result) => { },
  onPreDecryption: async () => true,
  onPostDecryption: async (decryptedPayload) => { },
  onPreAuthorisation: async () => null,
  onPostAuthorisation: async (data) => { },
  onSubmitError: async (submitError) => { },
  onError: (error) => { }
};
```

| Callback | Description |
|  --- | --- |
| `onInit`() => void | Called after the Paze SDK is initialised for this component. |
| `onPresentmentResolved`(isVisible: boolean) => void | Called after presentment resolves with whether the button is shown. |
| `onPazeButtonClicked`(event: Event) => void | Promise<void> | Called when the native button is clicked, before checkout starts. |
| `onCheckoutComplete`(result: PazeCheckoutResult) => boolean | Promise<boolean> | Called when `checkout()` returns `COMPLETE`. Return `true` to proceed to `complete()`, or `false` to cancel. If omitted, the SDK proceeds automatically. |
| `onCheckoutIncomplete`(result: PazeCheckoutResult) => void | Promise<void> | Called when checkout ends without completion or is rejected by merchant validation. |
| `onComplete`(result: PazeCompleteResult) => void | Promise<void> | Called after `complete()` succeeds. Use for manual decryption workflows. |
| `onPreDecryption`() => boolean | Promise<boolean> | Called before SDK decryption. Return `true` to allow SDK decryption, or `false` for manual decryption. |
| `onPostDecryption`(decryptedPayload: PazeDecryptTokenResponse) => void | Promise<void> | Called after the SDK decrypts the secured payload. |
| `onPreAuthorisation`() => boolean | PazeTransactionInitData | null | Promise<...> | Called before transaction submission. Return `false` to abort, `null`/`true` to proceed, or provide `riskScreeningData`. |
| `onPostAuthorisation`(data: PazePostAuthorisationData) => void | Promise<void> | Called after successful authorisation with transaction IDs and state. |
| `onSubmitError`(submitError: BaseSubmitResult) => void | Promise<void> | Called when transaction submission fails. |
| `onError`(error: BaseSdkException) => void | Called when a presentment, checkout, or decryption error occurs. |


For detailed callback payloads and event data structures, see [Events](/guides/checkout/components/web/paze/events).

## Decryption flow

### SDK-managed decryption (recommended)

By default, the SDK decrypts the secured payload after `complete()`:

```typescript
const config = {
  onCheckoutComplete: async (result) => {
    // Approve checkout to proceed
    return true;
  },

  onPreDecryption: async () => {
    // Allow SDK to decrypt (this is the default if omitted)
    return true;
  },

  onPostDecryption: async (decryptedPayload) => {
    console.log('Card network:', decryptedPayload.fundingData.cardNetwork);
  },

  onPostAuthorisation: async (data) => {
    console.log('Transaction ID:', data.systemTransactionId);
    await verifyPaymentOnBackend(data.systemTransactionId);
  }
};
```

### Manual decryption flow

Return `false` from `onPreDecryption` to handle decryption on your backend:

```typescript
const config = {
  onCheckoutComplete: async (result) => true,

  onPreDecryption: async () => false,

  onComplete: async (result) => {
    const securedPayload = result.completeDecodedResponse?.securedPayload;

    // POST to your backend, which calls the PXP decrypt-token API
    await fetch('/api/paze/decrypt', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ securedPayload })
    });
  }
};
```

When using manual decryption, you are responsible for calling the PXP `decrypt-token` endpoint and submitting the transaction from your backend. See [Backend decryption](/guides/checkout/components/web/paze/implementation#backend-decryption) for the full API reference.

## Fraud detection integration

### Address verification (AVS)

Set `performAVS: true` to include billing address from the decrypted payload in the transaction request when the **SDK submits the transaction**:

```typescript
const pazeButton = pxpSdk.create('paze-button', {
  billingPreference: 'ALL',
  performAVS: true
});
```

If you enable `performAVS`, set `billingPreference: "ALL"` so the Paze wallet returns a billing address for AVS. This applies only when the SDK manages decryption and authorisation. If you return `false` from `onPreDecryption`, add `addressVerification` to your backend transaction request using the billing address from the decrypt response.

### Kount risk screening

Pass risk screening data through `onPreAuthorisation`. Disable Kount device fingerprinting with `kountDisabled: true` on SDK initialisation:

```typescript
const pxpSdk = PxpCheckout.initialize({
  environment: 'test',
  session: sessionData,
  kountDisabled: false, // Set to true to disable Kount
  // ...
});

const pazeButton = pxpSdk.create('paze-button', {
  onPreAuthorisation: async () => ({
    riskScreeningData: {
      performRiskScreening: true,
      userIp: '192.168.1.100',
      account: {
        id: 'shopper-123',
        creationDateTime: '2024-01-15T10:30:00.000Z'
      }
    }
  })
});
```

## Methods

### mount()

Renders the Paze button in the specified container:

```typescript
const pazeButton = pxpSdk.create('paze-button', config);
pazeButton.mount('paze-container');
```

### unmount()

Removes the Paze button from the DOM:

```typescript
pazeButton.unmount();
```

## Examples

### Basic checkout button

```typescript
const pazeButton = pxpSdk.create('paze-button', {
  buttonRenderMode: 'static',
  emailAddress: 'customer@example.com',

  onCheckoutComplete: async () => true,

  onPostAuthorisation: async (data) => {
    await verifyPaymentOnBackend(data.systemTransactionId);
    window.location.href = '/order-confirmation';
  },

  onError: (error) => {
    console.error('Paze error:', error.ErrorCode, error.message);
    showError('Payment error. Please try again.');
  }
});

pazeButton.mount('paze-container');
```

### Dynamic presentment

```typescript
const pazeButton = pxpSdk.create('paze-button', {
  buttonRenderMode: 'dynamic',
  emailAddress: customerEmail,
  phoneNumber: '15551234567',

  onPresentmentResolved: (isVisible) => {
    if (!isVisible) {
      showAlternativePaymentMethods();
    }
  },

  onCheckoutComplete: async () => true,
  onPostAuthorisation: async (data) => {
    await verifyPaymentOnBackend(data.systemTransactionId);
  }
});
```

### Enterprise payment with fraud detection

```typescript
const pazeButton = pxpSdk.create('paze-button', {
  buttonRenderMode: 'dynamic',
  emailAddress: 'customer@example.com',
  phoneNumber: '15551234567',
  billingPreference: 'ALL',
  acceptedPaymentCardNetworks: ['VISA', 'MASTERCARD'],
  performAVS: true,
  style: { color: 'pazeblue', shape: 'pill', label: 'check out with' },

  onCheckoutComplete: async (result) => {
    // Server-side order validation before proceeding
    return await validateOrderOnBackend(result);
  },

  onPreAuthorisation: async () => ({
    riskScreeningData: {
      performRiskScreening: true,
      userIp: '192.168.1.100',
      account: { id: 'shopper-123', creationDateTime: '2024-01-15T10:30:00.000Z' }
    }
  }),

  onPostAuthorisation: async (data) => {
    if (data.state === 'Authorised') {
      await verifyPaymentOnBackend(data.systemTransactionId);
      window.location.href = `/success?id=${data.merchantTransactionId}`;
    }
  },

  onSubmitError: async (submitError) => {
    console.error('Submit error:', submitError);
    showError('Payment failed. Please try again.');
  }
});
```

## Configuration interfaces

### PazeButtonComponentConfig

```typescript
interface PazeButtonComponentConfig extends BaseComponentConfig {
  buttonRenderMode?: 'static' | 'dynamic';
  emailAddress?: string;
  phoneNumber?: string;
  paymentDescription?: string;
  billingPreference?: 'ALL' | 'ZIP_COUNTRY' | 'NONE';
  confirmLaunch?: boolean;
  sessionId?: string;
  acceptedShippingCountries?: string[];
  acceptedPaymentCardNetworks?: Array<'VISA' | 'MASTERCARD' | 'DISCOVER'>;
  cobrand?: PazeCobrandConfig[];
  enhancedTransactionData?: PazeEnhancedTransactionDataConfig;
  style?: PazeButtonStyleConfig;
  performAVS?: boolean;
  onInit?: () => void;
  onPresentmentResolved?: (isVisible: boolean) => void;
  onPazeButtonClicked?: (event: Event) => void | Promise<void>;
  onCheckoutComplete?: (result: PazeCheckoutResult) => boolean | Promise<boolean>;
  onCheckoutIncomplete?: (result: PazeCheckoutResult) => void | Promise<void>;
  onComplete?: (result: PazeCompleteResult) => void | Promise<void>;
  onCustomValidation?: () => Promise<boolean>;
  onPreDecryption?: () => boolean | Promise<boolean>;
  onPostDecryption?: (decryptedPayload: PazeDecryptTokenResponse) => void | Promise<void>;
  onPreAuthorisation?: () => boolean | PazeTransactionInitData | null | Promise<boolean | PazeTransactionInitData | null>;
  onPostAuthorisation?: (data: PazePostAuthorisationData) => void | Promise<void>;
  onSubmitError?: (submitError: BaseSubmitResult) => void | Promise<void>;
  onError?: (error: BaseSdkException) => void;
}
```

### PazeButtonStyleConfig

```typescript
interface PazeButtonStyleConfig {
  color?: 'white' | 'whitewithoutline' | 'midnightblack' | 'pazeblue';
  shape?: 'default' | 'rectangle' | 'pill';
  label?: 'checkout' | 'check out with' | 'Donate with';
  disableMaxHeight?: boolean;
}
```

### PazeCobrandConfig

```typescript
interface PazeCobrandConfig {
  cobrandName: string;
  benefitsOffered?: boolean;
}
```