> For the complete documentation index, see [llms.txt](https://docs.optty.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optty.com/widget/display-widgets.md).

# Display Widgets

## Overview

Display widgets promote available payment method options to consumers before they reach checkout, helping reduce cart abandonment. All widget content and styling is configured centrally from the **Universal Payments Platform (UPP)** and rendered on the storefront through the Optty widget SDK or an e-commerce platform plugin.

Optty provides four configurable display widgets:

| Widget             | Storefront location                     | Typical use                                     |
| ------------------ | --------------------------------------- | ----------------------------------------------- |
| **Footer**         | Site-wide footer                        | General awareness of pay-later availability     |
| **Product List**   | Category / product listing page         | Per-product instalment messaging in listings    |
| **Product Detail** | Product detail page + quick view        | Instalment estimate and hover detail on the PDP |
| **Cart**           | Cart page (+ mini-cart where supported) | Reinforce pay-later before checkout             |

Widgets only display once at least one payment provider has been configured and Optty payments are enabled.

> **Note:** Optty also offers checkout / payment-option and mini-cart widgets. These are outside the scope of this guide, which focuses on the four widgets configurable on the Widgets page (Footer, Product List, Product Detail, Cart).

## Pre-Requisites

Make sure that you have followed the steps for [Widget Setup and Integration](/widget/widget-setup-and-integration.md) before implementing the individual widgets into your site.

Before configuring widgets in the UPP, confirm:

* **UPP access** — Login credentials for the Optty Universal Payments Platform.
* **At least one payment provider configured** — Widgets render the live list of available providers; if none are enabled, widgets will not display.
* **Optty payments enabled on the storefront** — Widgets only display when the Optty payment integration is active.
* **Widget SDK embedded / plugin installed** — The Optty widget loader script (or the platform plugin) must be present, and your storefront domain whitelisted with Optty.
* **Widget token** — A widget/session token is used to load the correct provider options.

## Display Widget Examples

<figure><img src="/files/HnaStLlG4gxEcIu2GLgW" alt="" width="375"><figcaption><p>Logos</p></figcaption></figure>

<figure><img src="/files/Sae31WQAnaF0g0absVCT" alt="" width="359"><figcaption><p>product-box-widget</p></figcaption></figure>

<figure><img src="/files/MpSrDFTTsQoe9OU7DEMo" alt="" width="375"><figcaption><p>footer-widget</p></figcaption></figure>

## Display Widget Code Example

To test this we recommend forking this example and entering your widget token from the UPP found under 'view profile' when hovering your user on the top right.

{% embed url="<https://codesandbox.io/p/sandbox/pqzq3l>" %}

***

## Display Widget Configuration

From the UPP you can customise each widget to fit in with your site's styling from the **Widgets** tab found on the left sidebar. Here you can toggle different themes for each widget and update details such as font, colours and text.

### Accessing Widget Configuration in the UPP

1. Log in to the UPP for the relevant environment (**upp.qa.optty.com** for Sandbox, or your Production URL).
2. In the left-hand navigation, select **Widgets**. The page header reads "Widgets – Tailor your widgets to your specific preferences."
3. Use the four tabs across the top to switch between widgets: **Footer**, **Product List**, **Product Detail**, and **Cart**.
4. Configure the selected widget, then use **Preview Widget** (top right) to review, and **Save & Publish** to make changes live.

<figure><img src="/files/4TCfgYT6Dwgkgjag1mal" alt="UPP Widget Configuration Dashboard"><figcaption><p>UPP Widget Configuration Dashboard</p></figcaption></figure>

### Configuration Concepts

Each widget shares the same set of controls:

#### Visibility

A simple On/Off toggle that controls whether the widget appears on the consumer-facing site. Switching a widget Off shows a confirmation dialog before it is hidden:

> "Are you sure you would like to disable this widget? The widget will no longer display on your consumer-facing site and will be hidden until enabled again." Choose **Disable** to confirm or **Cancel** to keep it on.

#### Select Widget Style (Theme 1 / Theme 2)

Every widget offers two preset layouts. The fields shown in the **Style** and **Text** sections change depending on which theme is selected:

* **Theme 1** — the richer layout. Depending on the widget it can include a brand logo, both a primary and secondary colour, separate heading and body fonts, and several text fields.
* **Theme 2** — a streamlined layout. Typically a single primary colour and fewer text fields (often a single heading line).

#### Style

* **Brand Logo** (Theme 1, Footer only) — upload via click or drag-and-drop. Transparent `.png` recommended. Maximum 1 MB; recommended dimensions 500 × 500 px.
* **Colours** — Primary (and Secondary where shown). Enter a hex value (e.g. `#5031EA`) or use the colour picker with RGB sliders and eyedropper.
* **Fonts** — Heading and Body (some themes expose Heading only). Available options include **AvenirNext** and **ProximaNova**.

#### Text

Copy fields vary by widget and theme — Body Text, Primary Text, Secondary Text, Tooltip Text, Hover Heading/Body/Extra Text, or a single Heading Text. The exact set for each widget is listed in the sections below.

#### Preview Widget

Opens a panel on the right that renders the widget using current settings, alongside the live list of available payment provider logos. Use **Close Preview** to return to the editor. Preview reflects unsaved edits, so it is useful for checking copy and colours before publishing.

> **Note:** Preview doesn't show an uploaded logo — that will reflect on the actual site where the same merchant configs are used.

#### Save & Publish

Persists the configuration and pushes it live. Changes are **not** visible on the storefront until they are published. On some platforms (e.g. Salesforce) you may also need to clear the platform cache for changes to appear.

***

## Widget Configuration Reference

### Footer Widget

**Placement:** the storefront footer, shown site-wide.

| Section            | Theme 1 fields                            | Theme 2 fields  |
| ------------------ | ----------------------------------------- | --------------- |
| Visibility         | On / Off toggle                           | On / Off toggle |
| Style – Brand Logo | Yes (transparent .png, ≤1 MB, 500×500 px) | Not available   |
| Style – Colours    | Primary + Secondary                       | Primary only    |
| Style – Fonts      | Heading + Body                            | Heading only    |
| Text               | Body Text                                 | Body Text       |

Provider logos are rendered automatically beneath the body text based on the providers enabled for the account.

> **Sample Body Text:** "Pay for your order in instalments or direct from your bank. Your linked debit or credit card will be charged on a weekly or monthly basis based on your preference."

**Theme 1 — Footer widget**

<figure><img src="/files/X1DE4NTdkmq8kkoYaKbJ" alt="Footer widget Theme 1"><figcaption><p>Footer widget — Theme 1</p></figcaption></figure>

**Theme 2 — Footer widget**

<figure><img src="/files/VI75lzo20xxwMnloMZJP" alt="Footer widget Theme 2"><figcaption><p>Footer widget — Theme 2</p></figcaption></figure>

***

### Product List Widget

**Placement:** the product listing / category page.

**Theme 1 — Product List widget**

<figure><img src="/files/B5AhDuc1yDeyxNIdDcyX" alt="Product List widget Theme 1"><figcaption><p>Product List widget — Theme 1</p></figcaption></figure>

**Theme 2 — Product List widget**

<figure><img src="/files/Xc9geuzOURjbWFJh5MjG" alt="Product List widget Theme 2"><figcaption><p>Product List widget — Theme 2</p></figcaption></figure>

***

### Product Detail Widget

**Placement:** the product detail page (and quick-view, where supported).

| Section         | Theme 1 fields                                                                      | Theme 2 fields  |
| --------------- | ----------------------------------------------------------------------------------- | --------------- |
| Visibility      | On / Off toggle                                                                     | On / Off toggle |
| Style – Colours | Primary + Secondary                                                                 | Primary only    |
| Style – Fonts   | Heading + Body                                                                      | Heading + Body  |
| Text            | Primary Text, Secondary Text, Hover Heading Text, Hover Body Text, Hover Extra Text | Heading Text    |

The **Hover** fields control the tooltip shown when a shopper hovers the widget. The widget typically displays an instalment estimate (for example, "From **\[AMOUNT]** p/w, interest free") alongside provider logos.

> **Sample copy (Theme 1):**
>
> * **Primary Text:** "Pay Later"
> * **Secondary Text:** "Pay later"
> * **Hover Heading Text:** "Buy now, pay later"
> * **Hover Body Text:** "Pay for your order in instalments. Your linked debit or credit card will be charged on a weekly or monthly basis based on your preferences."
> * **Hover Extra Text:** "Displayed option available at checkout"

**Theme 1 — Product Detail widget**

<figure><img src="/files/TEsiBZXM9EcgIPF0Wsfq" alt="Product Detail widget Theme 1"><figcaption><p>Product Detail widget — Theme 1</p></figcaption></figure>

Selecting the information icon triggers the following overlay:

<figure><img src="/files/aPtT4YNgts8mkxq7tmLT" alt="Product Detail widget Theme 1 info overlay"><figcaption><p>Product Detail widget — Theme 1 info overlay</p></figcaption></figure>

<figure><img src="/files/aPtT4YNgts8mkxq7tmLT" alt="Product Detail widget Theme 1 additional view"><figcaption><p>Product Detail widget — Theme 1 additional view</p></figcaption></figure>

**Theme 2 — Product Detail widget**

<figure><img src="/files/KYki8iAXpHO4uQxMzdH5" alt="Product Detail widget Theme 2"><figcaption><p>Product Detail widget — Theme 2</p></figcaption></figure>

Clicking on the payment provider icon triggers the following overlay (checkout content, configured for that provider):

<figure><img src="/files/Tr7GgzNsfHbL0jZuPYXE" alt="Product Detail widget Theme 2 provider overlay"><figcaption><p>Product Detail widget — Theme 2 provider overlay</p></figcaption></figure>

<figure><img src="/files/Tr7GgzNsfHbL0jZuPYXE" alt="Product Detail widget Theme 2 additional view"><figcaption><p>Product Detail widget — Theme 2 additional view</p></figcaption></figure>

***

### Cart Widget

**Placement:** the cart page (and mini-cart, where supported).

| Section         | Theme 1 fields               | Theme 2 fields  |
| --------------- | ---------------------------- | --------------- |
| Visibility      | On / Off toggle              | On / Off toggle |
| Style – Colours | Primary only                 | Primary only    |
| Style – Fonts   | Heading + Body               | Heading + Body  |
| Text            | Primary Text, Secondary Text | Heading Text    |

The Cart widget renders the primary/heading text with an instalment estimate (for example, "From **\[AMOUNT]** per month over **\[N]** month(s)") and provider logos.

> **Sample copy:**
>
> * **Primary Text (Theme 1):** e.g. your product/price line
> * **Secondary Text (Theme 1):** "Interested? Select the pay later option on checkout"
> * **Heading Text (Theme 2):** Heading text

**Theme 1 — Cart widget**

<figure><img src="/files/21YPE09WQCERytLL4iU0" alt="Cart widget Theme 1"><figcaption><p>Cart widget — Theme 1</p></figcaption></figure>

**Theme 2 — Cart widget**

<figure><img src="/files/MwEHKQRK8lgRSaMcBTja" alt="Cart widget Theme 2"><figcaption><p>Cart widget — Theme 2</p></figcaption></figure>

***

## Customisation Best Practices

* **Align to brand.** Set Primary/Secondary colours and Heading/Body fonts to match your storefront.
* **Use a clean logo.** Upload a transparent `.png` within the size limits (≤1 MB, \~500×500 px) so it sits cleanly on any background.
* **Keep copy short and benefit-led.** Lead with the customer benefit ("Pay later", "interest free") and keep within any provider/regulatory disclosure requirements.
* **Preview both themes.** Switch between Theme 1 and Theme 2 in Preview before deciding; the field set differs between them.
* **Test in Sandbox first.** Validate on QA, then replicate in Production and switch the SDK host.
* **Always Save & Publish.** Changes are not live until published; clear platform/browser cache if they don't appear immediately.
* **Confirm at least one provider is enabled.** Widgets render the live provider list; with none enabled, nothing shows.

## Troubleshooting

| Symptom                          | Likely cause                                                                                                                               | Resolution                                                                                                                                                                            |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Widget not displaying at all     | Optty payments not enabled; no provider configured; Visibility set to Off; changes not published; SDK not embedded; domain not whitelisted | Enable Optty payments and at least one provider; set Visibility On; Save & Publish; confirm the loader script is present and the domain is whitelisted with correct merchant configs. |
| Changes not appearing            | Not published; platform or browser cache; still pointing at the sandbox host                                                               | Save & Publish; clear platform/browser cache; confirm the production SDK URL is used.                                                                                                 |
| Logo not showing / looks wrong   | Unsupported format or oversized file                                                                                                       | Use a transparent `.png` ≤1 MB, \~500×500 px.                                                                                                                                         |
| Wrong providers or amounts shown | Amount not passed to the widget; currency/initial amount misconfigured; expired token                                                      | Pass the correct amount/currency on init; refresh the widget/session token.                                                                                                           |
| Styling not applied              | Field belongs to the other theme; theme mismatch                                                                                           | Confirm the intended theme is selected; the available fields change per theme.                                                                                                        |
| Preview panel appears blank      | Widget render not available in preview for the current selection                                                                           | Re-check configuration/theme; verify on the storefront after publishing.                                                                                                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.optty.com/widget/display-widgets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.