---
title: Paypage Within an Iframe
slug: payments/paypage-within-an-iframe
description: Embed the Unaric Payments paypage inside an iframe for secure, seamless checkout on your website or portal.
docTags: 
createdAt: 2025-02-15T02:30:58.133Z
---

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

:::hint{type="warning"}
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 [support@unaric.com](mailto\:payment-support@unaric.com). 

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.&#x20;

## 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. Th&#x65;**&#x20;postMessage** content is always a simple string.

The following table describes the **postMessage&#x20;**&#x65;vents 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&#x20;**&#x65;vents, 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:

1. Convert the **postMessage** string (**aspPageSizeMessage**) to a JSON object using `JSON.parse()`.
2. Access the width and height values from the parsed JSON object to resize the iframe.

:::BlockQuote
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);
:::