Hosted Components LogoHosted-Components

DHPP

Dynamic Embeddable payment capture form

Dynamic HPP

The Dynamic Hosted Payment Page provides a secure, customizable payment form that can be embedded into any web application. This guide explains how to integrate and customize the payment form using our preview page as a reference.

Preview Page

Our preview page (preview.html) demonstrates a complete implementation of the payment form in a typical checkout scenario. It includes:

  1. A payment form section with the embedded iframe
  2. An order summary section showing transaction details
  3. Interactive customization controls for testing different configurations

Page Structure

<div class="checkout-grid">
	<!-- Payment Form Section -->
	<div class="payment-section">
		<h2>Payment Method</h2>
		<p>Below is the payment capture form embedded in an iFrame.</p>
		<div class="iframe-container">
			<iframe
				name="payment_methods"
				title="Payment Methods"
				allow="payment"
				scrolling="no"
			></iframe>
		</div>
	</div>

	<!-- Order Summary Section -->
	<div class="order-summary">
		<h2>Order Summary</h2>
		<div class="summary-item">
			<span>Premium Package</span>
			<span>$199.00</span>
		</div>
		<!-- Additional summary items -->
	</div>
</div>

Embedding the Payment Form

Basic Implementation

To embed the payment form in your application, use the following iframe code:

<iframe
	name="payment_methods"
	title="Payment Methods"
	src="https://main.d6x9wlghvzkti.amplifyapp.com/embed"
	allow="payment"
	scrolling="no"
	style="width: 100%; border: none;"
></iframe>

Configuration Options

URL Parameters

Customize the payment form using URL parameters:

<iframe
	src="https://main.d6x9wlghvzkti.amplifyapp.com/embed?merchantId=YOUR_MERCHANT_ID&countryCode=AU&paymentMethods=VISA,MASTERCARD,BANK&showFeePricing=true&termsandconditions=https://your-domain.com/terms"
></iframe>

Available parameters:

  • merchantId: Your Ezypay merchant ID. This parameter is optional if your JWT token contains a merchant_id claim, as the system will automatically extract it from the token. However, providing it explicitly will override the token value.
  • countryCode: Two-letter country code (e.g., "AU", "NZ", "SG")
  • paymentMethods: Comma-separated list of payment methods (e.g., "BANK,VISA,MASTERCARD,AMEX,PAYTO")
  • showFeePricing: Boolean parameter to control the visibility of fee pricing information (e.g., "true" or "false"). When enabled, displays applicable transaction fees and service charges for the selected payment methods. Note: Requires merchantId parameter or a JWT token with merchant_id claim.
  • termsandconditions: URL to your merchant-specific terms and conditions document. When provided, this will be displayed alongside Ezypay's terms and conditions in the payment form. Note: Requires merchantId parameter or a JWT token with merchant_id claim.
  • customerId: Customer ID in UUID format. When provided, after payment form is submitted, the created payment method token will be automatically linked to this customer ID. If not provided, only the token will be generated without linking. Note: Requires merchantId parameter or a JWT token with merchant_id claim.
  • displayexistingpaymentmethods: Boolean parameter to control the display of a customer's existing payment methods (e.g., "true" or "false"). When set to "true", the form will display any previously saved payment methods for the specified customer. Note: Requires both merchantId (or JWT token with merchant_id) and customerId parameters to function correctly.
  • setasprimary: Boolean parameter to force set the new payment method as the customer's primary payment method without showing the checkbox to the user (e.g., "true" or "false"). This option automatically sets the payment method as primary without user input. Note: Requires customerId parameter to function correctly.
  • setasprimary2: Boolean parameter to show the "Set as primary payment method" checkbox to the user (e.g., "true" or "false"). This option displays a checkbox that allows the user to choose whether to set the payment method as primary. Note: Requires customerId parameter to function correctly.

Example with fee pricing, terms and conditions, and hidden Ezypay details:

<iframe
	src="https://main.d6x9wlghvzkti.amplifyapp.com/embed?countryCode=AU&paymentMethods=VISA,MASTERCARD,BANK&showFeePricing=true&termsandconditions=https://your-domain.com/terms"
></iframe>

Example with customer ID, displaying existing payment methods, and setting as primary:

<iframe
	src="https://main.d6x9wlghvzkti.amplifyapp.com/embed?countryCode=AU&customerId=CUSTOMER_UUID&displayexistingpaymentmethods=true&paymentMethods=VISA,MASTERCARD,BANK&setasprimary=true"
></iframe>

Example with customer ID and showing the "Set as primary payment method" checkbox:

<iframe
	src="https://main.d6x9wlghvzkti.amplifyapp.com/embed?countryCode=AU&customerId=CUSTOMER_UUID&paymentMethods=VISA,MASTERCARD,BANK&setasprimary2=true"
></iframe>

Important: The merchant ID is required for the payment form to function correctly. This can be provided either through the merchantId URL parameter or it will be automatically extracted from the JWT token if it contains a merchant_id claim. Without a merchant ID, features like fee pricing and merchant terms and conditions will not work.

Customization

Theme Customization

Use postMessage to customize the form's appearance, either by updating the available CSS variables or by updating the CSS classes:

iframe.contentWindow.postMessage(
	{
		type: 'THEME_UPDATE',
		variables: {
			'--colorPrimary': '#FF5733',
			'--fontFamily': 'Inter',
		},
		classes: {
			'.InputField': {
				border: '1px solid #e0e0e0',
				'border-radius': '4px',
			},
			'.InputLabel': {
				'font-weight': '500',
				color: '#333',
			},
		},
	},
	'https://main.d6x9wlghvzkti.amplifyapp.com' // Ezypay's HPP URL
);

Available Global CSS Variables

:root {
	--fontFamily: 'Inter', Arial, Helvetica, sans-serif;
	--fontSizeBase: 16px;
	--fontSizeHeading1: 1.25rem;
	--fontSizeHeading2: 1rem;
	--fontSizeHeading3: 0.875rem;
	--fontSizeHeading4: 0.75rem;
	--spacingUnit: 0.25rem;
	--borderRadius: 0.5rem;
	--borderWidth: 1px;
	--borderColor: #e5e7eb;
	--colorPrimary: hsl(24 91% 56%);
	--colorTextTitle: #111827;
	--colorTextGeneral: #52525b;
	--colorTextSubtle: #6b7280;
	--colorTextHeading1: #111827;
	--colorTextHeading2: #52525b;
	--colorBackgroundPage: hsl(0 0% 100%);
	--colorBackgroundContainerPrimary: #fafafa;
	--colorBackgroundContainerSecondary: #ffffff;
	--colorBackgroundContainerHover: #f4f4f5;
	--colorDanger: #dc2626;
}
#VariableDescriptionApplicable to
1fontFamilySet the font family throughout hosted payments pageAll text elements
2fontSizeBaseBase font size for general textDefault size for body text. Default value is 16px
3fontSizeHeading1Font size of heading 1 textApplicable to (refer to mockup):
  • "Payment Details"
  • "Information"
Success/failure page:
  • "Payment method created"
  • "Failed to create payment method"
4fontSizeHeading2Font size of heading 2 textApplicable to (refer to mockup):
  • "Existing payment method(s)"
  • "Add a new payment method"
  • "Fee Pricing"
  • "For any questions on payments"
  • "By continuing, I hereby agree with Ezypay terms and conditions and <merchant name> terms and conditions"
5fontSizeHeading3Font size of heading 3 textApplicable to (refer to mockup):
  • "Mastercard ending with **** 5153 - John Doe"
  • "Bank"
  • "BSB Number"
  • "Account Number"
  • "Account Holder Name"
  • "The following may be charged when billing with Ezypay"
  • " Standard Bank Fee $1.00"
  • "Standard Amex Fee 0.8% + $1.00"
  • "Standard MasterVisa Fee 0.1% + $1.00"
6fontSizeHeading4Font size of heading 4 textApplicable to (refer to mockup):
  • "Note: A minimum transaction fee amount may apply"
  • "Powered by EZYPAY"
  • "Set as Primary payment method"
7spacingUnitVertical spacing between componentsControls spacing between components, labels & content
8borderRadiusRoundedness of edges in the bordersApplied to buttons, input fields, and containers
9borderWidthBorder width of payment method creation sectionApplied to borders of input fields and containers
10borderColorColor of borders for input fields and sectionsApplied to all borders throughout the form
11colorPrimaryThematic color to be applicable throughout Hosted Payment PageApplicable to:
12colorTextTitleMain heading text colorUsed for primary headings and important text
13colorTextGeneralGeneral text color for most contentApplied to regular body text throughout the form
14colorTextSubtleSubtle text color for secondary informationApplied to help text, hints, and secondary information
15colorTextHeading1Text color for heading 1By default takes value from colorTextTitle variable. Applicable to (refer to mockup):
  • "Payment Details"
  • "Information"
16colorTextHeading2Text color for heading 2By default takes value from colorTextGeneral variable. Applicable to (refer to mockup):
  • "Existing payment method(s)"
  • "Add a new payment method"
  • "Fee Pricing"
  • "For any questions on payments"
17colorBackgroundPageBackground color of the entire pageApplied to the page background
18colorBackgroundContainerPrimaryBackground color for primary/selected containersApplied to selected accordion items, cards, and main containers
19colorBackgroundContainerSecondaryBackground color for nested/unselected containersApplied to nested containers, unselected accordion items, and secondary panels
20colorBackgroundContainerHoverBackground color when hovering over containersApplied when hovering over clickable containers
21colorDangerColor used to indicate errors or invalid inputsApplied to error messages, validation errors, and warning indicators

Available CSS Classes

1. Form Elements

ClassDescriptionPseudo-classesPseudo-elementsStates
.InputFieldInput field container:hover, :focus::placeholder--invalid
.InputLabelInput field labels:hover, :focus--invalid
.InputErrorError message styling:hover, :focus
.RadioButtonRadio button container:hover, :focus
.RadioButtonInnerInner circle of radio button--selected, --disabled
.CheckboxContainerCheckbox container:hover
.CheckboxInputCheckbox input element:hover, :focus--checked, --disabled
.CheckboxLabelCheckbox label:hover, :focus
.SubmitButtonSubmit button:hover, :focus, :disabled

2. Accordion Components

ClassDescriptionPseudo-classesStates
.AccordionItemIndividual accordion item:hover, :focus
.AccordionTriggerAccordion trigger button:hover, :focus
.AccordionTriggerLabelAccordion trigger label
.AccordionContentAccordion content area:hover, :focus
.MethodAccordionItemAdd new payment method accordion item:hover, :focus
.MethodAccordionTriggerAdd new payment method accordion trigger:hover, :focus
.MethodAccordionTriggerLabelAdd new payment method accordion trigger label
.MethodAccordionTriggerDescriptionAdd new payment method accordion description
.MethodAccordionContentAdd new payment method accordion content area:hover, :focus
.InformationAccordionItemInformation accordion item:hover, :focus
.InformationAccordionTriggerInformation accordion trigger:hover, :focus
.InformationAccordionTriggerLabelInformation accordion trigger label
.InformationAccordionContentInformation accordion content

3. Fee Pricing Components

ClassDescriptionPseudo-classesStates
.FeePricingLabelFee pricing label--primary
.FeePricingContentFee pricing content container
.FeePricingTableHeaderFee pricing table header
.FeePricingTableRowFee pricing table row:hover

4. Existing Payment Method Components

ClassDescriptionPseudo-classesStates
.MethodListItemContainerExisting payment method list item container:hover--primary
.MethodListItemLabelExisting payment method list item label
.MethodListItemDescriptionExisting payment method list item description
.MethodPrimaryBadgePrimary badge

5. Contact Details Components

ClassDescriptionPseudo-classesStates
.EzypayDetailsLabelEzypay details label
.EzypayDetailsContentEzypay details content
.EzypayEmailEzypay email link:hover

6. Terms & Conditions Components

ClassDescriptionPseudo-classesStates
.TermsLabelTerms and conditions label
.TermsLinkTerms and conditions link:hover

7. Submit Results Components

ClassDescriptionPseudo-classesStates
.SubmitResultsIconSubmit results icon
.SubmitResultsIconBackgroundSubmit results icon background
.SubmitResultsTitleSubmit results title
.SubmitResultsContentSubmit results content

Responsive Height

The iframe automatically adjusts its height based on content. Add this event listener to handle height changes:

window.addEventListener('message', function (e) {
	if (e.data && e.data.type === 'resize') {
		const iframe = document.querySelector('iframe');
		if (iframe) {
			iframe.style.height = `${e.data.height}px`;
		}
	}
});

Payment Method Response Payload

When a payment method is successfully created, a message is sent to the parent window with the following structure:

Card Payment Response

{
  type: 'PAYMENT_METHOD_TOKEN',
  paymentMethodToken: 'token-value',
  card: {
    accountHolderName: 'Cardholder Name',
    expiryYear: 'YY',
    expiryMonth: 'MM',
    type: 'CARD',
    last4: '1234',  // Last 4 digits of card
    first6: '123456', // First 6 digits of card
    countryCode: 'AU', // Country code
    tokenDetails: null,
    tokenized: false
  },
  bank: null,
  payTo: null,
  wallet: null
}

Bank Account Response

{
  type: 'PAYMENT_METHOD_TOKEN',
  paymentMethodToken: 'token-value',
  card: null,
  bank: {
    accountHolderName: 'Account Holder Name'
    // Additional bank details may be included
  },
  payTo: null,
  wallet: null
}

Customer Linking Response

When a customer ID is provided, the payment method will be linked to the customer's account. The response will include additional properties indicating the status of this linking operation:

{
  // Standard payment method properties as shown above
  // ...

  // Additional customer linking information
  customerID: 'customer-id', // Will be null if linking failed
  link_status: true  // Boolean indicating if linking was successful
}

Primary Payment Method

The payment method can be set as the customer's primary method in three ways:

  1. Force-set as primary using the setasprimary=true URL parameter
  2. Allow user selection with checkbox using the setasprimary2=true URL parameter
  3. Legacy approach using setasprimary=true URL parameter (when the other parameters are not provided)

The determination logic is:

  • Primary if setasprimary=true (forced primary)
  • Primary if setasprimary2=true AND the checkbox is checked
  • Primary if setasprimary=true AND neither of the above parameters are provided AND the checkbox is checked

Handling the Response

To handle the payment method response:

window.addEventListener('message', (event) => {
	if (event.data && event.data.type === 'PAYMENT_METHOD_TOKEN') {
		// Handle the payment method token
		console.log('Payment method token:', event.data.paymentMethodToken);

		// If customer linking was requested, check the status
		if (event.data.hasOwnProperty('link_status')) {
			if (event.data.link_status) {
				console.log('Successfully linked to customer:', event.data.customerID);
			} else {
				console.log('Failed to link payment method to customer');
			}
		}
	}
});

Logging and Monitoring

Integration Logging

When integrating the payment form, implement structured logging to track events and troubleshoot issues:

// Create a logging utility for your payment integration
const PaymentLogger = {
	info: (message, data = {}) => {
		console.log(`[Payment Integration] ${message}`, {
			timestamp: new Date().toISOString(),
			level: 'info',
			...data,
		});
	},
	error: (message, error, data = {}) => {
		console.error(`[Payment Integration] ${message}`, {
			timestamp: new Date().toISOString(),
			level: 'error',
			error: error?.message || error,
			stack: error?.stack,
			...data,
		});
	},
};

// Usage in your payment form integration
window.addEventListener('message', (event) => {
	if (event.data && event.data.type === 'PAYMENT_METHOD_TOKEN') {
		PaymentLogger.info('Payment method token received', {
			paymentMethodToken: event.data.paymentMethodToken,
			paymentType: event.data.card ? 'CARD' : event.data.bank ? 'BANK' : 'OTHER',
		});

		// Handle customer linking
		if (event.data.hasOwnProperty('link_status')) {
			if (event.data.link_status) {
				PaymentLogger.info('Customer linking successful', {
					customerId: event.data.customerID,
					isPrimary: event.data.isPrimary,
				});
			} else {
				PaymentLogger.error('Customer linking failed', null, {
					customerId: event.data.customerID,
				});
			}
		}
	}
});

// Log iframe loading events
const iframe = document.querySelector('iframe[name="payment_methods"]');
iframe.addEventListener('load', () => {
	PaymentLogger.info('Payment form loaded successfully');
});

iframe.addEventListener('error', (error) => {
	PaymentLogger.error('Payment form failed to load', error);
});

Error Handling and Logging

Implement comprehensive error handling with proper logging:

// Enhanced error handling for payment integration
const handlePaymentError = (error, context = {}) => {
	PaymentLogger.error('Payment integration error', error, {
		context,
		userAgent: navigator.userAgent,
		url: window.location.href,
		timestamp: new Date().toISOString(),
	});

	// Show user-friendly error message
	showUserError('Payment form is temporarily unavailable. Please try again.');
};

// Usage examples
try {
	// Payment form operations
	iframe.contentWindow.postMessage(themeUpdate, targetOrigin);
} catch (error) {
	handlePaymentError(error, { operation: 'theme_update' });
}

Example Implementation

You can find a complete example implementation in our preview.html file, which includes:

  • Full checkout page layout
  • Theme customization controls
  • Payment method selection
  • Responsive design
  • Order summary integration

The preview page serves as a reference implementation that you can use as a starting point for your own integration.