Paypage Within an Iframe

You can embed paypage templates within an iframe on your existing website, instead of using it as a standalone page.

This functionality is only available for websites using modern encryption (TLS 1.2 or higher).

Requirements and recommendations

Whitelist your domain

In case Content Security Policy (CSP) blocks paypage access in your live environment, you need to whitelist your domain. To do so, contact the Unaric Payments team at [email protected].

Domain whitelisting is not required for test environments.

Sizing

Ensure your <iframe> element is appropriately sized to display the entire payment form without a scrollbar. We recommend a minimum size of 500px width and 1000px height.

Security

The parent page hosting the iframe must be served over HTTPS (TLS 1.2 or newer) so users can verify the security of the payment form, indicated by the browser's security indicators for the parent page. Non-secure pages cannot host the Unaric Payments payment page in an iframe.

PostMessage Events

When the template operates in iframe mode, it sends standard postMessage events to the parent page. These events allow the parent page to react to different stages of the payment process. The postMessage content is always a simple string.

The following table describes the postMessage events and their corresponding values:

Text String	Description
asp--redir URL	Sent when the payment process redirects to an external authorisation page, such as PayPal. The string value contains the URL of the external page. Upon receiving this message, the parent page can close the iframe and open the URL in a new tab or window.
asp--exit-screen	Sent when the payment success screen is loaded within the iframe.
asp--error--value MESSAGE	Sent when the payment error screen is loaded within the iframe. The string value contains the error message displayed to the user.
asp--error-screen	Sent when the payment error screen is loaded within the iframe.
asp--error	Sent when the user clicks the Close Without Retry button on the payment error screen.
asp--complete	Sent when the user clicks the Finish button on the payment success screen.
asp--cancel	Sent when the user clicks the cancel link on the main payment page.
asp--processing	Sent when the processing animation is displayed, indicating that the user has submitted the payment form and the payment is being processed.
asp--pcdialog	Sent when the postcode lookup dialog is displayed.
asp--dddialog	Sent when the Direct Debit confirmation dialog box is displayed. This message allows the parent frame to refocus the iframe using window.scrollTo(0,0).
aspPageSizeMessage	Sent when the payment page changes size. Allows the iframe to respond to sizing changes in the payment page content.

Implementing a PostMessage listener

To handle these postMessage events, you need to implement a listener in the parent HTML page. This listener allows you to execute specific actions based on the received messages. For example, to close the iframe when the payment success screen is displayed, you can check for the asp--exit-screen text content in the postMessage body.

Page size example

To dynamically adjust the iframe size based on the payment page content:

Convert the postMessage string (aspPageSizeMessage) to a JSON object using JSON.parse().

Access the width and height values from the parsed JSON object to resize the iframe.

let size = JSON.parse(aspPageSizeMessage); // To get the width value as an integer: let width = parseInt(size.aspPageSize.width); // To get the height value, similarly use: // let height = parseInt(size.aspPageSize.height); // Example of using the size object to set iframe dimensions (assuming you have a function called 'showForm'): // showForm(size.aspPageSize.width, size.aspPageSize.height);