> ## Documentation Index
> Fetch the complete documentation index at: https://docs.choosefloat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget & modal implementation

> Which host to load the product widget and "How it works" modal from in sandbox and production, how each one decides which instalment terms to show, and what to check before go-live.

The [product page widget](https://docs.choosefloat.com/guides/product-widget.md) and the "How it works" modal it opens are static files on Float's CDN. This page covers the parts of an implementation that the embed snippet doesn't: which host to use in each environment, how the instalment terms are chosen, what shoppers see when you don't send any, and how to open the modal yourself.

## Environments

There is one host per environment. Everything else (paths, parameters, behaviour) is identical, so the host should be the only thing that changes between your sandbox and production builds.

| | Sandbox | Production |
| - | - | - |
| Widget script | `https://staging-widgets.float.co.za/uk/widget.js` | `https://widgets.choosefloat.com/uk/widget.js` |
| "How it works" modal | `https://staging-widgets.float.co.za/uk/modal.html` | `https://widgets.choosefloat.com/uk/modal.html` |
| `public_id` terms are read from | Sandbox (`uat-secure.choosefloat.com`) | Production (`secure.choosefloat.com`) |
| Pair with API base URL | `https://uat-secure.choosefloat.com` | `https://secure.choosefloat.com` |

> [!WARNING]
>
> Keep the pairs together. A `public_id` only exists in the environment it was issued for, so a sandbox `public_id` on the production host (or the reverse) finds no terms. Drive the widget host from the same setting that switches your API base URL.

The sandbox host receives changes before production does, so it is the place to check a new widget release against your theme. Don't ship it to shoppers.

## Add the widget

Place the script tag where the messaging should render, usually directly below the price:

```html Sandbox theme={null}
<script src="https://staging-widgets.float.co.za/uk/widget.js?price=600&instalments=2,3,4"></script>
```

```html Production theme={null}
<script src="https://widgets.choosefloat.com/uk/widget.js?price=600&instalments=2,3,4"></script>
```

`price` is in **Pounds** (`600` is £600.00). The full parameter reference, `floatUpdate` for prices that change without a reload, and multi-widget pages are covered in the [product page widget guide](https://docs.choosefloat.com/guides/product-widget.md).

## Which terms are shown

The widget and the modal each look for terms in the same order and stop at the first that applies:

**1. instalments**

The terms you list, e.g. `instalments=2,3,4`. Use this when your platform already knows the terms you offer.

**2. public\_id**

Your integration's public id. Float looks up your configured term rules and uses the terms that apply to the price, so the messaging tracks what checkout will offer. Answers are cached for five minutes, so a change to your terms can take that long to appear.

**3. Fallback**

Neither was sent, or the `public_id` lookup found nothing. See [the fallback](#the-fallback) below.

For a £600 product:

| You send | Product page line | Modal |
| - | - | - |
| `instalments=2,3,4` | "Or as low as £150.00 over 4 months" | Picker with 2, 3 and 4; 4 selected |
| `instalments=4` | "Or as low as £150.00 over 4 months" | 4 instalments, no picker |
| `public_id=…` and your terms for £600 are 2, 3, 4 | "Or as low as £150.00 over 4 months" | Picker with 2, 3 and 4; 4 selected |
| `public_id=…` and Float has no terms for that price or merchant | Nothing is rendered | - |
| Neither | "Or as low as £200.00 over 3 months" | Picker with 2, 3, 4 and 6; 6 selected; a note that options may differ |

![Two product cards. The first, with no terms sent, reads 'Or as low as £200.00 over 3 months interest-free'. The second, with instalments 2, 3 and 4, reads 'Or as low as £150.00 over 4 months interest-free'.](https://mintcdn.com/choosefloat/Vkv26Rj6ZAHMszds/images/widget-terms-vs-fallback.png?fit=max\&auto=format\&n=Vkv26Rj6ZAHMszds\&q=85\&s=0e4e281d4e3fcb283a199faec855e969)

The same £600 product with no terms sent (left) and with instalments=2,3,4 (right).

The line always advertises the longest term, because that gives the lowest instalment. The modal opens on the longest term and lets the shopper switch between the others. Its schedule is split the way checkout splits a real plan: equal instalments, with any rounding remainder on the last one.

## The fallback

When an embed sends neither `instalments` nor `public_id`, Float doesn't know which terms you offer, so it shows generic ones:

* The product page line reads "Or as low as £200.00 over 3 months interest-free, using your credit card."
* The modal offers 2, 3, 4 and 6 instalments with 6 selected, and adds the line "The available instalment options may differ based on the retailer."

```text Fallback theme={null}
https://staging-widgets.float.co.za/uk/modal.html?price=60000
```

```text With your terms theme={null}
https://staging-widgets.float.co.za/uk/modal.html?price=60000&instalments=2,3,4
```

![The How it works modal with a picker offering 2, 3, 4 and 6 instalments, 6 selected, a schedule splitting £600 into six instalments, and the line 'The available instalment options may differ based on the retailer.'](https://mintcdn.com/choosefloat/Vkv26Rj6ZAHMszds/images/modal-fallback.png?fit=max\&auto=format\&n=Vkv26Rj6ZAHMszds\&q=85\&s=5174d11732ce7f7c15139eee67e74b77)

The fallback modal for a £600 product: 2, 3, 4 and 6 instalments with 6 selected, and the note that options may differ.

![The How it works modal with a picker offering 2, 3 and 4 instalments, 4 selected, and a schedule splitting £600 into four instalments.](https://mintcdn.com/choosefloat/Vkv26Rj6ZAHMszds/images/modal-with-terms.png?fit=max\&auto=format\&n=Vkv26Rj6ZAHMszds\&q=85\&s=9bd0f0ba2c496eb0c2f2002a95f3cc0f)

The same modal when the embed sends instalments=2,3,4: only those terms, 4 selected, and no note.

The fallback keeps older embeds working, but it can advertise a term you don't offer. Send `instalments` or `public_id` so shoppers see your real terms and the note disappears.

> [!NOTE]
>
> A widget with `public_id` is stricter than one with nothing: if Float has no terms for the price, it renders nothing on the product page rather than guess. If you want messaging to show regardless, send `instalments`.

## Open the modal yourself

The widget opens the modal for you. Load it directly only when you have your own "How it works" trigger, for example on a cart page, a payment-method list, or a landing page. It is a plain page, so an iframe inside your own lightbox or a link in a new tab both work:

```html theme={null}
<iframe
  src="https://widgets.choosefloat.com/uk/modal.html?price=60000&instalments=2,3,4"
  title="How Float works"
  loading="lazy"></iframe>
```

| Param | Required | Description |
| - | - | - |
| `price` | No | The amount for the worked example, in **pence** (`60000` is £600.00). Without it the example uses £600. |
| `instalments` | No | One term or a comma-separated list, as on the widget. `installments` is also accepted. |
| `public_id` | No | Used only when `instalments` is absent. With a `price`, the modal shows your terms for that price; without one, every term you offer. If nothing is found it shows the fallback. |

> [!WARNING]
>
> The units differ. The widget takes `price` in Pounds; the modal takes it in pence. When the widget opens the modal it converts for you, so this only matters if you build the modal URL yourself.

The modal has no close button of its own; the lightbox or tab you open it in provides that.

## Content Security Policy

If your site sends a Content-Security-Policy, allow the widget host for the environment you're in:

| Directive | Needed for |
| - | - |
| `script-src` | Loading `widget.js` |
| `frame-src` | The modal, which opens in an iframe |
| `connect-src` | The terms lookup, only if you use `public_id` |

A blocked terms lookup looks the same as "no terms": the product page line doesn't render.

## Check it in sandbox

**1. Point at the sandbox host**

Load the widget from `staging-widgets.float.co.za` with your sandbox `public_id`, or with the `instalments` you offer.

**2. Compare the terms with checkout**

Open a product page, then start a [sandbox checkout](https://docs.choosefloat.com/guides/testing-and-go-live.md) for the same amount. The terms in the modal's picker should match the terms the payment page offers. If you use term rules that vary by basket size, repeat with a price in each band.

**3. Confirm you are not on the fallback**

Open the modal. If you see "The available instalment options may differ based on the retailer", the embed is sending neither parameter, or the `public_id` found no terms.

**4. Try the edges**

A price that changes without a reload (variant, quantity, discount) should update the line through `floatUpdate`. A product with no price should render no widget at all. A listing page with several products should show each one's own amount.

## Go live

* Switch the widget host to `widgets.choosefloat.com` in the same change that switches your API base URL to `secure.choosefloat.com`.
* Replace the sandbox `public_id` with your production one.
* Update your Content-Security-Policy to the production host.
* Load a live product page, open the modal, and confirm the terms match your production checkout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.