> This page is for Afterpay Online Developer, version Main (default).
> For other versions, use one of these documentation indexes:
> - Main (default): https://developers.afterpay.com/afterpay-online-developer/main/llms.txt
> - v1: https://developers.afterpay.com/afterpay-online-developer/v-1/llms.txt
> - Chinese: https://developers.afterpay.com/afterpay-online-developer/chinese/llms.txt

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

# Messaging Implementation

On-Site Messaging adds pay-over-time messaging to your store’s website. For example, in the picture below the messaging is:

*Or 4 interest-free installments of \$25.00 with Afterpay ⓘ*

![image14.png](/_fern-img/74ad71367e686c8166a9a0fb16759948deff863d282be583384c0e46f1955f12.webp)

Updates to the messaging are automatic, and a specific set of messaging logic is designed for your products. Use our On-Site Messaging Editor in the Business Hub to customize, preview, and manage your messaging.

## Requirements

To use On-site Messaging you must:

* Be an existing Afterpay merchant
* Have a direct integration with Afterpay
* Have at least one retail website live and ready for use; a Sandbox environment is also available for testing

> **Note**
>
> If you already have Afterpay Messaging through the Dynamic Widget or the JavaScript library, we recommend you replace these with On-Site Messaging. See the [Migration page](/afterpay-online-developer/main/guides/afterpay-messaging/migration) for details.

## Business hub environments

On-site Messaging configurations are environment-specific and tied to your production and sandbox merchant accounts. See our page on [Business Hub Access](/afterpay-online-developer/guides/welcome/business-hub) or speak to your dedicated account manager if you need assistance getting user access to the Business Hub links below.

To test, you will need access to the Sandbox Portal and a set of Sandbox credentials. Click the links below for these:

| Environment | Link                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| Sandbox     | [https://hub.sandbox.afterpay.com/onsite-messaging](https://hub.sandbox.afterpay.com/onsite-messaging) |
| Production  | [https://hub.afterpay.com/onsite-messaging](https://hub.afterpay.com/onsite-messaging)                 |

## Sandbox testing

We recommend that you start by configuring On-Site Messaging in the [Sandbox Business Hub](https://hub.sandbox.afterpay.com) to review the Afterpay messaging on your development store before you go live in production.

To test, you need access to the Sandbox Business Hub.

Before deploying to production, ensure that:

* Messaging appears correctly on all product pages
* Messaging updates when price changes
* Messaging appears correctly on cart page
* Multiple products in cart show correct total installment amount
* Ineligible products/carts correctly hide messaging
* Messaging is responsive on mobile devices
* All required attributes are properly populated

When you are satisfied with your testing, you're ready to go to the production [Business Hub](https://hub.afterpay.com) to configure your messaging. From this portal, you can configure Afterpay messaging for the live site.

## On-Site Messaging quickstart guide

### Configure On-Site Messaging

Start by accessing either environment's Business Hub:

* [Sandbox](https://hub.sandbox.afterpay.com) — we recommend that you start here
* [Production](https://hub.afterpay.com)

1. Once logged in, navigate to the On-Site Messaging tab in the sidebar
   ![OSM-AP-implementation-1.png](/_fern-img/b89460b230bc3c741c6acc6a2c616ee6e5bdc576f56d07d5f68ec9c6ab71ec09.webp)

2. From the On-Site Messaging tab, go to the Placements sub-page
   ![OSM-AP-implementation-2.png](/_fern-img/c5b8529667df59582cab116aca8e37976e820b404ec32b1b97f26b972c8821f6.webp)

3. Select the Product or Cart page to customize your messaging from the options available. You can make adjustments to the logo, text size, and theme by placement.
   ![OSM-implementation-3.png](/_fern-img/e76c410fc84449b5d78dd1588f1bbef39336c585cae0dec5c5a55cdaea59047e.webp)

4. Navigate to the Settings sub-page to find additional advanced configuration options.
   ![OSM-AP-implementation-4.png](/_fern-img/cc940850c2dc331310cdb5c5d3670e75620ebbe228c0953fb422c9fec2c2abb5.webp)

5. Once your configuration settings are ready, click the Implementation Guide sub-page and follow the instructions there to add the messaging to your associated environment storefront in three steps.

Here's an example from the production On-Site Messaging tab:
![OSM-AP-implementation-5.png](/_fern-img/e968bff462a407fd888e8ec433d35dbacdb2599bd102df9549f586be44ea6faa.webp)

### Add On-Site Messaging to your storefront

To display installment messaging on your storefront, add the respective `<square-placement>` tag from the Implementation Guide to the product page and cart page files in your codebase. Place the messaging immediately below the price element of the product and the total element of the cart.

Example square placement on product page:

```javascript
<square-placement
  data-mpid="{Replace with your MPID}"
  data-placement-id="{Replace with your product Placement ID}"
  data-page-type="product"
  data-amount="{Replace with your own price variable}"
  data-currency="{Replace with your own currency variable}"
  data-consumer-locale="{Replace with consumer locale variable}"
  data-item-skus="{Replace with SKU variable}"
  data-item-categories="{Replace with category variable}"
  data-is-eligible="true"
>
</square-placement>
```

Make sure to correctly configure the following dynamic properties for each `<square-placement>` tag added on your site:

1. Set the `data-amount` with the amount that appears on the page to calculate the installments. Keep the `data-mpid` and `data-placement-id` attributes in place with their current values unchanged.

2. Set the `data-currency` to the customer's currency and `data-consumer-locale` to the customer's country.

3. Set `data-item-skus` to any unique product identifier you use, provided as a string. If you have multiple products in the cart, separate them with a comma.

4. Set `data-item-categories` as one or more category names for the relevant product. This is provided as a string or for multiple tegories, separate them with a comma.

5. To restrict a product from sale with Afterpay, set the `data-is-eligible` attribute to false. To restrict a cart from sale with Afterpay, set the `data-cart-is-eligible` attribute to false. This is optional.