Learn about how to configure the Paze button component for Web.
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 |
|---|---|
buttonRenderModeenum | Controls presentment. Defaults to "static".Possible values:
|
emailAddressstring | The shopper's email address. Required for dynamic presentment. Validated as RFC 5322 when provided. |
phoneNumberstring | 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.
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 |
|---|---|
buttonRenderModeenum | Controls button presentment. Defaults to "static".Possible values:
|
emailAddressstring | 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(). |
phoneNumberstring | A phone number in US E.164 format without +. Required when buttonRenderMode is "dynamic". Takes precedence over emailAddress at checkout when both are set. |
paymentDescriptionstring | A statement descriptor forwarded to Paze. Maximum 25 characters. |
billingPreferenceenum | Billing address collection in the Paze popup. Defaults to "ALL".Possible values:
|
confirmLaunchboolean | When true, Paze may show a confirmation popup before checkout. |
sessionIdstring | Optional session ID echoed back by Paze. Defaults to the SDK session ID. |
acceptedShippingCountriesstring[] | The list of accepted shipping countries, in ISO 3166-1 alpha-2 format. |
acceptedPaymentCardNetworksstring[] | Accepted card networks. Defaults to VISA, MASTERCARD, and DISCOVER. |
cobrandPazeCobrandConfig[] | Optional cobrand entries for partner branding in the Paze wallet. |
enhancedTransactionDataobject | Optional checkout metadata forwarded to Paze. See Enhanced transaction data. |
stylePazeButtonStyleConfig | Official Paze button styling. See Styling. |
performAVSboolean | 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).
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']
}
});| Property | Description |
|---|---|
ecomData.cartContainsGiftCardboolean | Whether the cart contains a gift card. |
ecomData.orderForPickupboolean | Whether the order is for in-store or curbside pickup. |
ecomData.orderQuantitystring | Order item count as a string. |
ecomData.orderHighestCoststring | Highest line-item cost as a string. |
ecomData.finalShippingAddressobject | Shipping address with line1, city, state, zip, countryCode, and optional line2 and name. |
processingNetworkstring[] | Preferred card networks for processing (VISA, MASTERCARD, or DISCOVER). |
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
}
};| Property | Description |
|---|---|
colorenum | The button colour theme. Possible values:
|
shapeenum | The button shape. Possible values:
|
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.
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.
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);
}
};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.
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.
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'
}
}
})
});Renders the Paze button in the specified container:
const pazeButton = pxpSdk.create('paze-button', config);
pazeButton.mount('paze-container');Removes the Paze button from the DOM:
pazeButton.unmount();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');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);
}
});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.');
}
});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;
}interface PazeButtonStyleConfig {
color?: 'white' | 'whitewithoutline' | 'midnightblack' | 'pazeblue';
shape?: 'default' | 'rectangle' | 'pill';
label?: 'checkout' | 'check out with' | 'Donate with';
disableMaxHeight?: boolean;
}interface PazeCobrandConfig {
cobrandName: string;
benefitsOffered?: boolean;
}