Skip to content

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:

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

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)
});
PropertyDescription
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.
style
PazeButtonStyleConfig
Official Paze button styling. See 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.

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']
  }
});
PropertyDescription
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:

const config = {
  style: {
    color: 'pazeblue',
    shape: 'pill',
    label: 'check out with',
    disableMaxHeight: false
  }
};
PropertyDescription
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.

Event handling

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) => { }
};
CallbackDescription
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.

Decryption flow

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

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:

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

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:

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:

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

unmount()

Removes the Paze button from the DOM:

pazeButton.unmount();

Examples

Basic checkout button

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

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

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

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

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

PazeCobrandConfig

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