Dynamic messaging widget

🚧

Availability

The Afterpay Dynamic Messaging Widget is currently available in Afterpay Regions and Clearpay UK.

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 Afterpay account manager.

For Clearpay EU please continue to use our JavaScript Library.

The Afterpay Dynamic Messaging widget allows you to display the standard Afterpay messaging together with Afterpay 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:
<script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>
  1. Initialise the widget by adding the following code into the <body> of any page you wish to display Afterpay 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 Afterpay payment option.
<div id="afterpay-messaging-widget"></div>
  1. Add the following code into your web pages to configure the look and feel of the widget:
<script>
    function createMessaging () {
        new AfterPay.Widgets.Placement({
            // Ensure target matches the id specified in step 3
            target: "#afterpay-messaging-widget",
            locale: "en-AU",
            // 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 Afterpay          
             // team
            publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
            attributes: {
                currency: "AUD",
                amount: "300",
                promoRenderStyle:"promo-with-get-and-payment", 
            }
        });
    }
</script>
  1. 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.

Replacing an existing Afterpay messaging widget

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

  1. Add the following code to the <head> element of your web pages:
<script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>
  1. In your web page HTML, find and copy the afterpay placement element. It should look something like this:
<afterpay-placement
    data-amount="300"
    data-locale="en_AU"
    data-currency="AUD">
      data-...
</afterpay-placement>
  1. Open the dynamic widget migration helper and enter your public key, region, context, and paste the code snippet copied in the last step into the Current tag: section.
  2. Copy the code in the New placement javascript field.
  3. Add the following code snippet to the <head> section of your web page, and paste in the code copied in the previous step:
<script>
    function createMessaging () {
    // Paste new placement code from step 4 here
    }
</script>
  1. Initialise the widget by adding the following code into the <body> of any page you wish to display Afterpay 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 Afterpay payment option.
<div id="afterpay-messaging-widget"></div>
  1. Search for and delete the following code snippet:
<script src="https://js.afterpay.com/afterpay-1.x.js" data-analytics-enabled async></script>
  1. Search for and delete the <afterpay-placement> tag and all code inside it. It will probably look similar to the following code snippet:
<afterpay-placement
    data-amount="300"
    data-locale="en_AU"
    data-currency="AUD">
      data-...
</afterpay-placement>

Configuring the dynamic messaging widget

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

Attribute nameTypeSupported valuesDescription
targetstring, requiredA CSS selector that matches an element on your site, for example, #afterpay-messaging-widget
localestring, requireden-US
en-AU
en-CA
en-GB
en-NZ
Description of your store region.
contextstring, requiredPRODUCT_PAGE
CART
CHECKOUT
ORDER_CONFIRMATION
The type of page that this instance of the widget will appear on.
publicKeystring, requiredYour Afterpay public key, for example 6e757026-0fcd-4fdc-a858-13017c8f584f
promoRenderStylestring, optionalpromo-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.
promoAnimationStylestring, optionalblink
toggle
alternate-diagonals
This attribute lets you select the style of animation for the discount amount. You can select from three different variants.
stylesparent category, optionalsee below for style attributesContains configurable style parameters.

Style configuration options

Style attributeTypeDescriptionExamples
fontFamilystring, optionalThe name of a font available to the browser.Sans-Serif
Arial
fontFacesstring, optionalAn array of all custom font faces that you intend to reference in the fontFamily definition.See Font Faces section below.
linkColorstring, optionalA CSS color for links appearing in the placement.red
rgb(123,123,123)
logoBadgeWidthstring, optionalThe width of the Afterpay badge.2em
15px
textAlignstring, optionalA valid CSS text-align value.center
left
right
justify
textColorstring, optionalA CSS color for the text that appears in the placement (excludes the Afterpay 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.

AttributeSupported ValuesExamples
familyThe custom name for your font. This field is required.MyGreatFont
sourcesAn array of sources for your custom font face. This field is required.See Font Sources section below.
ascentOverrideSee https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-overridenormal
90%
descentOverrideSee https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-overridenormal
90%
displaySee https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-displayauto
block
featureSettingsSee https://developer.mozilla.org/en-US/docs/Web/CSS/font-feature-settingsnormal
revert
stretchSee https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretchexpanded
100%
styleSee https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stylenormal
oblique 30deg
variantSee https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variantsmall-caps
unset
variationSettingsSee https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variation-settingsnormal
"xhgt" 0.7
weightSee https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight400
bold
unicodeRangeSee https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-rangeU+26
U+0025-00FF

Here is a full example of a font face definition.

new AfterPay.Widgets.Placement({
    target: "#afterpay-messaging-widget",
    locale: "en-AU",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "AUD",
        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 user’s computer.

Remote Font

AttributeSupported ValuesExamples
urlThe URL to the remote font. This field is required.https://somewebsite.com/path/to/font.woff
formatThe format of the font.woff
woff2

Local Font

AttributeSupported ValuesExamples
localA 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:

new AfterPay.Widgets.Placement({
    target: "#afterpay-messaging-widget",
    locale: "en-AU",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "AUD",
        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.

new AfterPay.Widgets.Placement({
    target: "#afterpay-messaging-widget",
    locale: "en-AU",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "AUD",
        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:

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

Valid values for the placementPosition option are the same as the valid position values defined here.

All configuration attributes of the static Afterpay messaging widget are applicable to the dynamic messaging widget, and can be found here.

🚧

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.

USA only - Pay Monthly Instalment messaging

If you are a merchant based in the USA and have a direct integration to Afterpay, you can offer Pay Monthly.

Merchants who have consumer lending (Pay Monthly) enabled can display specific Product Detail Page (PDP) and shopping cart messaging in the existing widget.

📘

What is Pay Monthly?

Pay Monthly is a monthly payment product is a long-term, instalment-based lending option. It gives your customers more flexible ways to pay for high-value orders greater than $400.

How does Pay Monthly work in practice? Messaging appears when the cart or item price is greater than or equal to $400. It is displayed up to the data-max value that is returned. See the screenshots below:

306306

Your customer clicks the afterpay button on the shopping cart message.

604604

Two monthly payment options appear to the customer, who can select the option they want.

To add Pay Monthly, do the following:

  1. Access the iframe widget.
  2. Add aprLoansAvailable:"true" to the attributes object.

A full code example is below. The aprLoansAvailable attribute is below the amount attribute, and is set to "true".

<!doctype html>
<html>
 <head>
   <script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>
   <script>
     function createMessaging () {
       new AfterPay.Widgets.Placement({
         target: "#afterpay-messaging-widget",
         locale: "en-US",
         context: "PRODUCT_PAGE",
         publicKey: "00000000-0000-4000-0000-000000000000",
         attributes: {
           locale: "en_US",
           currency: "USD",
           amount: "420",
           aprLoansAvailable: "true",
         }
       });
     }
   </script>
 </head>
 <body>
   <div id="afterpay-messaging-widget"></div>
 </body>
</html>

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 KeyBehaviour
dollar-off-promotionShows a $20 off promotion.

🚧

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

Example:

<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-US",
            context: "CART",
            publicKey: "dollar-off-promotion",
            attributes: {
                amount: "300"
            }
        });
    }
</script>