> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developers.clearpay.co.uk/v-2/llms.txt
> - v1: https://developers.clearpay.co.uk/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.clearpay.co.uk/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.clearpay.co.uk/_mcp/server.

# Clearpay Dynamic Messaging Widget

> **Availability**
>
> Clearpay Dynamic Messaging Widget is currently only available in the UK and in Afterpay Regions.
>
> In order to use the dynamic messaging widget and all of its features you will require a "Public Key".  Public keys are not made available to all merchants. Should you have any questions please speak to your Clearpay account manager.

The Clearpay Dynamic Messaging widget allows you to display the standard Clearpay messaging together with Clearpay promo messaging during the shopping experience. The messaging can be shown on product pages, the cart, and the checkout pages.

## Integrating dynamic messaging for the first time

1. Add the following code snippet in the `<head>` section of your product, cart, and checkout web pages:

```html
<script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>
```

2. Initialise the widget by adding the following code into the `<body>` of any page you wish to display Clearpay messaging. We recommend that on product pages the messaging is immediately below the price, on cart pages the messaging is below the subtotal, and on checkout pages, the messaging is within the Clearpay payment option.

```html
<div id="afterpay-messaging-widget"></div>
```

3. Add the following code into your web pages to configure the look and feel of the widget:

```html
<script>
    function createMessaging () {
        new AfterPay.Widgets.Placement({
            // Ensure target matches the id specified in step 3
            target: "#afterpay-messaging-widget",
            locale: "en-GB",
            // Change to match the page you want to display the widget on
            context: "PRODUCT_PAGE",
             // Change to the public key provided to you by the Clearpay          
             // team
            publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
            attributes: {
                currency: "GBP",
                amount: "300",
                promoRenderStyle:"promo-with-get-and-payments"
            }
        });
    }
</script>
```

4. Configure the widget to suit your implementation. Locale, currency, context, and render style should be adjusted as necessary. For more information, see [configuring the dynamic widget](#configuring-the-dynamic-messaging-widget).

## Replacing an existing Clearpay messaging widget

To replace an existing Clearpay messaging widget with the dynamic widget, follow these steps:

1. Add the following code to the `<head>` element of your web pages:

```html
<script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>
```

2. In your web page HTML, find and copy the `afterpay placement` element. It should look something like this:

```html
<afterpay-placement
	data-amount="300"
	data-locale="en_GB"
	data-currency="GBP">
      data-...
</afterpay-placement>
```

3. Open the [dynamic widget migration helper](https://static.sandbox.afterpay.com/messaging-migration.html) and enter your public key, region, context, and paste the code snippet copied in the last step into the **Current `<afterpay-placement>` tag:** section.
4. Copy the code in the **New placement javascript** field.
5. Add the following code snippet to the `<head>` section of your web page, and paste in the code copied in the previous step:

```html
<script>
    function createMessaging () {
    // Paste new placement code from step 4 here
    }
</script>
```

5. Initialise the widget by adding the following code into the `<body>` of any page you wish to display Clearpay messaging. We recommend that on product pages the messaging is immediately below the price, on cart pages the messaging is below the subtotal, and on checkout pages, the messaging is within the Clearpay payment option.

```html
<div id="afterpay-messaging-widget"></div>
```

6. Search for and delete the following code snippet:

```html
<script src="https://js.afterpay.com/afterpay-1.x.js" data-analytics-enabled async></script>
```

7. Search for and delete the `<afterpay-placement>` tag and all code inside it. It will probably look similar to the following code snippet:

```html
<afterpay-placement
	data-amount="300"
	data-locale="en-GB"
	data-currency="GBP">
      data-...
</afterpay-placement>
```

## Configuring the dynamic messaging widget

There are a number of configuration options that can be adjusted .

| Attribute name      | Type                      | Supported values                                                                                                                                                     | Description                                                                                                                  |
| :------------------ | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
| target              | string, required          |                                                                                                                                                                      | A CSS selector that matches an element on your site, for example, #afterpay-messaging-widget                                 |
| locale              | string, required          | en-US  en-AU  en-CA  en-GB  en-NZ                                                                                                                                    | Description of your store region.                                                                                            |
| context             | string, required          | PRODUCT_PAGE  CART  CHECKOUT  ORDER_CONFIRMATION                                                                                                                     | The type of page that this instance of the widget will appear on.                                                            |
| publicKey           | string, required          |                                                                                                                                                                      | Your Clearpay public key, for example 6e757026-0fcd-4fdc-a858-13017c8f584f                                                   |
| promoRenderStyle    | string, optional          | `promo-only`  `promo-or-empty`  `promo-and-payments-or-empty`  `promo-and-payments`  `promo-with-get-and-payments-or-empty`  `promo-with-get-and-payments` (default) | This attribute lets you select the style in which you want to display the promo messaging.                                   |
| promoAnimationStyle | string, optional          | blink  toggle  alternate-diagonals                                                                                                                                   | This attribute lets you select the style of animation for the discount amount. You can select from three different variants. |
| styles              | parent category, optional | see below for style attributes                                                                                                                                       | Contains configurable style parameters.                                                                                      |

### Style configuration options

| Style attribute | Type             | Description                                                                                                  | Examples                      |
| :-------------- | :--------------- | :----------------------------------------------------------------------------------------------------------- | :---------------------------- |
| fontFamily      | string, optional | The name of a font available to the browser.                                                                 | Sans-Serif  Arial             |
| fontFaces       | string, optional | An array of all custom font faces that you intend to reference in the fontFamily definition.                 | See Font Faces section below. |
| linkColor       | string, optional | A CSS color for links appearing in the placement.                                                            | red  rgb(123,123,123)         |
| logoBadgeWidth  | string, optional | The width of the Clearpay badge.                                                                             | 2em  15px                     |
| textAlign       | string, optional | A valid CSS text-align value.                                                                                | center  left  right  justify  |
| textColor       | string, optional | A CSS color for the text that appears in the placement (excludes the Clearpay logo and promo amount styles). | red  rgb(123,123,123)         |

### Font Faces

The `fontFaces` style allows you to define one or many custom font faces that you will reference in your `fontFamily` definition for the widget.

The following defines the attributes of each font face option.

| Attribute         | Supported values                                                                                                                                                               | Examples                        |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |
| family            | The custom name for your font. This field is required.                                                                                                                         | MyGreatFont                     |
| sources           | An array of sources for your custom font face. This field is required.                                                                                                         | See Font Sources section below. |
| ascentOverride    | See [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override)                 | normal  90%                     |
| descentOverride   | See [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-override](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-override)               | normal  90%                     |
| display           | See [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display)                       | auto  block                     |
| featureSettings   | See [https://developer.mozilla.org/en-US/docs/Web/CSS/font-feature-settings](https://developer.mozilla.org/en-US/docs/Web/CSS/font-feature-settings)                           | normal  revert                  |
| stretch           | See [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretch](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretch)                       | expanded  100%                  |
| style             | See [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style)                           | normal  oblique 30deg           |
| variant           | See [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variant](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variant)                       | small-caps  unset               |
| variationSettings | See [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variation-settings](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variation-settings) | normal  "xhgt" 0.7              |
| weight            | See [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight)                         | 400  bold                       |
| unicodeRange      | See [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range)                     | U+26  U+0025-00FF               |

Here is a full example of a font face definition.

```html
new AfterPay.Widgets.Placement({
    target: "#afterpay-messaging-widget",
    locale: "en-GB",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "GBP",
        amount: "300"
        styles: {
            fontFamily: "CustomFont1, CustomFont2, sans-serif",
            fontFaces: [
              {
                family: "CustomFont1",
                sources: [
                  {
                    url: "https://example.com/CustomFont1.woff2",
                    format: "woff2"
                  },
                  {
                    url: "https://example.com/CustomFont1.woff",
                    format: "woff"
                  },
                  {
                    local: "-apple-system"
                  }
                ],
                display: "swap",
                ascentOverride: "normal",
                descentOverride: "normal",
                featureSettings: "normal",
                lineGapOverride: "normal",
                stretch: "50% 200%",
                style: "oblique 20deg 50deg',
                variant: "small-caps",
                variationSettings: "normal",
                weight: 400
                unicodeRange: "U+26"
              },
              {
                family: "CustomFont2",
                sources: [
                  {
                    url: "https://example.com/CustomFont2.woff2",
                    format: "woff2"
                  }
                ]
            ]
        }
    }
});
```

### Font Sources

A single font face can have a number of different sources. There are 2 kinds of font sources - a URL to a remote font, or a local font on a customer’s computer.

#### Remote Font

| Attribute | Supported Values                                    | Examples                                                                               |
| :-------- | :-------------------------------------------------- | :------------------------------------------------------------------------------------- |
| url       | The URL to the remote font. This field is required. | [https://somewebsite.com/path/to/font.woff](https://somewebsite.com/path/to/font.woff) |
| format    | The format of the font.                             | woff  woff2                                                                            |

#### Local Font

| Attribute | Supported Values                           | Examples      |
| :-------- | :----------------------------------------- | :------------ |
| local     | A local font name. This field is required. | -apple-system |

### Amount selector

The `amountSelectors` attribute is available as an alternative to the `amount` attribute, which allows you to select the content of an HTML element to use as the amount. This element will also be watched for any changes and the widget will be updated automatically. Here is an example of using this attribute:

```html
new AfterPay.Widgets.Placement({
    target: "#afterpay-messaging-widget",
    locale: "en-GB",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "GBP",
        amountSelectors: {
            amount: "#myamountelement"
        }
    }
});
```

### Amount mutation selector

The `mutation` attribute, allows you to watch for changes in content on an element that is not the amount element, to trigger an update of the amount present in your selected `amount` element. This is useful if product amount changes on your site trigger a reload of a parent element to the amount, meaning mutations on the amount itself will not be fired. Here is an example of this.

```html
new AfterPay.Widgets.Placement({
    target: "#afterpay-messaging-widget",
    locale: "en-GB",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "GBP",
        amountSelectors: {
            amount: "#myamountelement",
            mutation: "#someparentelement"
        }
    }
});
```

### Target selector

The `targetSelector` attribute functions as an alternative to the target attribute and allows you to place the widget adjacent to an existing element using a CSS selector (a target HTML element to place the widget inside is not required). Here is an example of using this option:

```html
new AfterPay.Widgets.Placement({
    targetSelector: {
        adjacentElement: "#myelement",
        placementPosition: "beforebegin"
    },
    locale: "en-GB",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "GBP",
        amount: "200"
    }
});
```

Valid values for the placementPosition option are the same as the valid position values [defined here](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML).

All configuration attributes of the static Clearpay messaging widget are applicable to the dynamic messaging widget, and can be found [here](/afterpayjs-reference).

> **Info**
>
> When using these attributes in the JavaScript snippet, they should be converted from snake case to camel case. For example payment-amount-is-bold would become paymentAmountIsBold, show-upper-limit would become showUpperLimit.

## Testing Promotion Messaging

When implementing the messaging widget, you may wish to manually enable a promotion to see how this appears on your site. When using the Sandbox version of afterpay.js you can enable promotion messaging using one of the following “test” public keys in your configuration.

| Public Key           | Behaviour                  |
| :------------------- | :------------------------- |
| dollar-off-promotion | Shows a £13 off promotion. |

> **Info**
>
> This public key only works when using the Sandbox version of afterpay.js - it will not work with the production version.

Example:

```html
<script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload="createMessaging()"></script>

<script>
    function createMessaging () {
        window.messagingWidget = new AfterPay.Widgets.Placement({
            target: "#afterpay-messaging-widget",
            locale: "en-GB",
            context: "CART",
            publicKey: "dollar-off-promotion",
            attributes: {
                amount: "300"
            }
        });
    }
</script>
```