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:
- A payment form section with the embedded iframe
- An order summary section showing transaction details
- 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;
}
# | Variable | Description | Applicable to |
---|---|---|---|
1 | fontFamily | Set the font family throughout hosted payments page | All text elements |
2 | fontSizeBase | Base font size for general text | Default size for body text. Default value is 16px |
3 | fontSizeHeading1 | Font size of heading 1 text | Applicable to (refer to mockup):
|
4 | fontSizeHeading2 | Font size of heading 2 text | Applicable to (refer to mockup):
|
5 | fontSizeHeading3 | Font size of heading 3 text | Applicable to (refer to mockup):
|
6 | fontSizeHeading4 | Font size of heading 4 text | Applicable to (refer to mockup):
|
7 | spacingUnit | Vertical spacing between components | Controls spacing between components, labels & content |
8 | borderRadius | Roundedness of edges in the borders | Applied to buttons, input fields, and containers |
9 | borderWidth | Border width of payment method creation section | Applied to borders of input fields and containers |
10 | borderColor | Color of borders for input fields and sections | Applied to all borders throughout the form |
11 | colorPrimary | Thematic color to be applicable throughout Hosted Payment Page | Applicable to:
|
12 | colorTextTitle | Main heading text color | Used for primary headings and important text |
13 | colorTextGeneral | General text color for most content | Applied to regular body text throughout the form |
14 | colorTextSubtle | Subtle text color for secondary information | Applied to help text, hints, and secondary information |
15 | colorTextHeading1 | Text color for heading 1 | By default takes value from colorTextTitle variable. Applicable to (refer to mockup):
|
16 | colorTextHeading2 | Text color for heading 2 | By default takes value from colorTextGeneral variable. Applicable to (refer to mockup):
|
17 | colorBackgroundPage | Background color of the entire page | Applied to the page background |
18 | colorBackgroundContainerPrimary | Background color for primary/selected containers | Applied to selected accordion items, cards, and main containers |
19 | colorBackgroundContainerSecondary | Background color for nested/unselected containers | Applied to nested containers, unselected accordion items, and secondary panels |
20 | colorBackgroundContainerHover | Background color when hovering over containers | Applied when hovering over clickable containers |
21 | colorDanger | Color used to indicate errors or invalid inputs | Applied to error messages, validation errors, and warning indicators |
Available CSS Classes
1. Form Elements
Class | Description | Pseudo-classes | Pseudo-elements | States |
---|---|---|---|---|
.InputField | Input field container | :hover , :focus | ::placeholder | --invalid |
.InputLabel | Input field labels | :hover , :focus | --invalid | |
.InputError | Error message styling | :hover , :focus | ||
.RadioButton | Radio button container | :hover , :focus | ||
.RadioButtonInner | Inner circle of radio button | --selected , --disabled | ||
.CheckboxContainer | Checkbox container | :hover | ||
.CheckboxInput | Checkbox input element | :hover , :focus | --checked , --disabled | |
.CheckboxLabel | Checkbox label | :hover , :focus | ||
.SubmitButton | Submit button | :hover , :focus , :disabled |
2. Accordion Components
Class | Description | Pseudo-classes | States |
---|---|---|---|
.AccordionItem | Individual accordion item | :hover , :focus | |
.AccordionTrigger | Accordion trigger button | :hover , :focus | |
.AccordionTriggerLabel | Accordion trigger label | ||
.AccordionContent | Accordion content area | :hover , :focus | |
.MethodAccordionItem | Add new payment method accordion item | :hover , :focus | |
.MethodAccordionTrigger | Add new payment method accordion trigger | :hover , :focus | |
.MethodAccordionTriggerLabel | Add new payment method accordion trigger label | ||
.MethodAccordionTriggerDescription | Add new payment method accordion description | ||
.MethodAccordionContent | Add new payment method accordion content area | :hover , :focus | |
.InformationAccordionItem | Information accordion item | :hover , :focus | |
.InformationAccordionTrigger | Information accordion trigger | :hover , :focus | |
.InformationAccordionTriggerLabel | Information accordion trigger label | ||
.InformationAccordionContent | Information accordion content |
3. Fee Pricing Components
Class | Description | Pseudo-classes | States |
---|---|---|---|
.FeePricingLabel | Fee pricing label | --primary | |
.FeePricingContent | Fee pricing content container | ||
.FeePricingTableHeader | Fee pricing table header | ||
.FeePricingTableRow | Fee pricing table row | :hover |
4. Existing Payment Method Components
Class | Description | Pseudo-classes | States |
---|---|---|---|
.MethodListItemContainer | Existing payment method list item container | :hover | --primary |
.MethodListItemLabel | Existing payment method list item label | ||
.MethodListItemDescription | Existing payment method list item description | ||
.MethodPrimaryBadge | Primary badge |
5. Contact Details Components
Class | Description | Pseudo-classes | States |
---|---|---|---|
.EzypayDetailsLabel | Ezypay details label | ||
.EzypayDetailsContent | Ezypay details content | ||
.EzypayEmail | Ezypay email link | :hover |
6. Terms & Conditions Components
Class | Description | Pseudo-classes | States |
---|---|---|---|
.TermsLabel | Terms and conditions label | ||
.TermsLink | Terms and conditions link | :hover |
7. Submit Results Components
Class | Description | Pseudo-classes | States |
---|---|---|---|
.SubmitResultsIcon | Submit results icon | ||
.SubmitResultsIconBackground | Submit results icon background | ||
.SubmitResultsTitle | Submit results title | ||
.SubmitResultsContent | Submit 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:
- Force-set as primary using the
setasprimary=true
URL parameter - Allow user selection with checkbox using the
setasprimary2=true
URL parameter - 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.