Migrating from Hosted Fields to Checkout SDK

This guide covers what to change when moving from Secure Hosting's Hosted Fields integration to the Monek Checkout SDK (checkout-js).

What's changing

	Hosted Fields	Checkout SDK
Script	`payments.monek.com/hostedfields/js/hostedFields.js`	`checkout-js.monek.com/monek-checkout.iife.js`
Auth	`shreference` + `checkcode` hidden fields	Public key passed to `Monek()`
Card iframe	Manual `<iframe>` tag in your HTML	SDK mounts into a `<div>` you provide
Payment data	Hidden `<input>` fields	JavaScript callbacks
Submit	`onclick="hfSend(...)"`	SDK intercepts form submit (or you call `triggerSubmission()`)
Outcome handling	Redirect via `successPage` global	`onSuccess` / `onError` / `onCancel` callbacks
Domain allowlist	Set in management portal	Not required
Express checkout	Not available	Apple Pay supported

Step-by-step migration

1. Update your script tag

Remove the old globals and script:

<!-- REMOVE -->
<script>var basketFormID = "basketform"; var successPage = "/thank-you";</script>
<script src="https://payments.monek.com/hostedfields/js/hostedFields.js"></script>

Add the Checkout SDK:

<!-- ADD -->
<script src="https://checkout-js.monek.com/monek-checkout.iife.js"></script>

2. Replace the iframe with a container div

Remove the manually-placed iframe and submit button:

<!-- REMOVE -->
<iframe src="https://payments.monek.com/hostedfields/hostedFields.php"
        style="border:0; display:block;" id="iframe-content"
        scrolling="no" width="80%" height="475"></iframe>
<button onclick="hfSend(basketFormID, successPage);" id="hfsubmit">Complete Order</button>

Add a plain container div inside your form, and keep (or add) a normal submit button:

<!-- ADD -->
<div id="checkout-container"></div>
<button type="submit">Complete Order</button>

The SDK will render its own iframe inside #checkout-container.

3. Replace hidden form fields with SDK callbacks

Remove the hidden fields:

<!-- REMOVE -->
<input type="hidden" name="shreference" value="shXXXXXX" />
<input type="hidden" name="checkcode" value="123456" />
<input type="hidden" name="transactionamount" value="5.00" />

These values are now supplied to the SDK via JavaScript callbacks (see step 4).

4. Initialise the SDK

Add an inline script (or move this to your own JS file) after the SDK script tag:

<script>
  (async () => {
    // Initialise with your public key (obtain from the Monek management portal)
    const sdk = await Monek('your-public-key');

    const options = {
      callbacks: {
        // Return the transaction amount and currency
        getAmount: () => ({
          major: '5.00',   // or read from your page: document.querySelector('[name="amount"]').value
          currency: '826'  // ISO-4217: 826 = GBP
        }),

        // Return a short order description
        getDescription: () => 'Order #12345',

        // Return cardholder/billing details
        getCardholderDetails: () => ({
          name:      document.querySelector('[name="billingName"]').value,
          email:     document.querySelector('[name="billingEmail"]').value,
          homePhone: document.querySelector('[name="billingPhone"]').value,
          billingAddress: {
            addressLine1: document.querySelector('[name="billingAddress1"]').value,
            addressLine2: document.querySelector('[name="billingAddress2"]').value,
            city:         document.querySelector('[name="billingCity"]').value,
            postcode:     document.querySelector('[name="billingPostcode"]').value,
            country:      '826' // ISO-4217: 826 = UK
          }
        })
      },

      completion: {
        mode: 'client',
        onSuccess: (ctx, { redirect }) => redirect('/thank-you'),
        onError:   (ctx, { reenable }) => {
          reenable();
          alert(ctx?.payment?.Message || 'Payment failed. Please try again.');
        },
        onCancel:  (ctx, { reenable }) => reenable()
      },

      countryCode: '826' // Your store's country
    };

    // Mount the card fields
    const checkout = sdk.createComponent('checkout', options);
    await checkout.mount('#checkout-container');
  })();
</script>

Where do I find my public key?
Log in to the Monek management portal and navigate to Settings → Integrations. Your Checkout Access Tokens will be listed there; click the + icon to create one if you don't have one yet. This replaces the shreference + checkcode combination.

5. Remove the domain allowlist entry (optional tidy-up)

With Hosted Fields you had to register your domain in the management portal under Company Details → Website. This is not required by the Checkout SDK, so you can remove that entry once you've fully migrated.

Full before/after example

Before (Hosted Fields)

<head>
  <script>
    var basketFormID = "basketform";
    var successPage  = "/thank-you";
  </script>
  <script src="https://payments.monek.com/hostedfields/js/hostedFields.js"></script>
</head>
<body>
  <form id="basketform">
    <input type="hidden" name="shreference"      value="shXXXXXX" />
    <input type="hidden" name="checkcode"         value="123456" />
    <input type="hidden" name="transactionamount" value="5.00" />

    <iframe src="https://payments.monek.com/hostedfields/hostedFields.php"
            style="border:0; display:block;" id="iframe-content"
            scrolling="no" width="80%" height="475"></iframe>

    <button onclick="hfSend(basketFormID, successPage);">Complete Order</button>
  </form>
</body>

After (Checkout SDK)

<head>
  <script src="https://checkout-js.monek.com/monek-checkout.iife.js"></script>
</head>
<body>
  <form id="payment-form">
    <div id="checkout-container"></div>
    <button type="submit">Complete Order</button>
  </form>

  <script>
    (async () => {
      const sdk = await Monek('your-public-key');

      const options = {
        callbacks: {
          getAmount:            () => ({ major: '5.00', currency: '826' }),
          getDescription:       () => 'Order #12345',
          getCardholderDetails: () => ({
            name:  'Jane Smith',
            email: 'jane@example.com',
            billingAddress: { postcode: 'SW1A 1AA', country: '826' }
          })
        },
        completion: {
          mode:      'client',
          onSuccess: (ctx, { redirect }) => redirect('/thank-you'),
          onError:   (ctx, { reenable }) => { reenable(); alert('Payment failed'); },
          onCancel:  (ctx, { reenable }) => reenable()
        },
        countryCode: '826'
      };

      const checkout = sdk.createComponent('checkout', options);
      await checkout.mount('#checkout-container');
    })();
  </script>
</body>

Optional: add Apple Pay (Express checkout)

Apple Pay is not available in Hosted Fields but is supported by the Checkout SDK. To add it, include an express container above your card fields and mount a second component:

<div id="express-container"></div>
<div id="checkout-container"></div>

const express = sdk.createComponent('express', options);
await express.mount('#express-container');

Apple Pay will only render on compatible browsers/devices where the user has it set up. The button hides automatically otherwise. Your Monek account must also have Apple Pay enabled — contact Monek support if you need this activated.

Theming

The Checkout SDK exposes theming options that weren't available in Hosted Fields. You can match your brand using CSS variables or a styling config object:

:root {
  --monek-input-focus: #0ea5e9;
}

const options = {
  styling: {
    theme: 'light', // or 'dark'
    core: { backgroundColor: '#ffffff', borderRadius: 8 },
    inputs: { inputBackgroundColor: '#f9f9f9' }
  },
  // ...
};

Summary checklist

Replace the Hosted Fields <script> with the Checkout SDK script
Remove var basketFormID and var successPage globals
Replace the <iframe> tag with <div id="checkout-container">
Remove shreference, checkcode, and transactionamount hidden inputs
Replace onclick="hfSend(...)" with type="submit" on your button
Initialise the SDK with your public key and wire up the required callbacks
Handle outcomes in onSuccess, onError, onCancel instead of relying on a redirect URL global
(Optional) Remove the domain allowlist entry from the management portal
(Optional) Add Apple Pay with the express component

What's changing​

Step-by-step migration​

1. Update your script tag​

2. Replace the iframe with a container div​

3. Replace hidden form fields with SDK callbacks​

4. Initialise the SDK​

5. Remove the domain allowlist entry (optional tidy-up)​

Full before/after example​

Before (Hosted Fields)​

After (Checkout SDK)​

Optional: add Apple Pay (Express checkout)​

Theming​

Summary checklist​