Skip to main content

Hosted Form

What is a Hosted Form?​

The Hosted Form is a secure, PCI-DSS compliant payment form that can be embedded directly into your checkout page. It provides a simple integration path while maintaining a good balance between security and UI customization.

Purse hosts the form and manages all sensitive data, so you don’t have to handle card information yourself.

When should I use a Hosted Form?​

Use the Hosted Form if:

  • You only need to collect a single payment method (e.g., credit card).
  • You want a straightforward integration with minimal effort.
  • You require PCI compliance without implementing complex iframe orchestration.
  • You want to offer a consistent, branded payment experience with moderate customization.
Need deeper customization?

For more granular control over the UI (e.g., styling individual input fields), consider using Hosted Fields instead.

Before You Start​

Make sure you have a client session.

Integration Steps​

1. Load the Headless Checkout SDK​

Add this script to your checkout page:

<script type="module">
  import * as Purse from "https://cdn.purse-sandbox.com/headless-checkout/latest/purse.esm.js";
</script>

ℹ️ The SDK is served from Purse’s CDN to meet PCI-DSS requirements. Do not self-host this file.

2. Initialize Headless Checkout​

Use your client session data to create an instance of the checkout:

<div id="purse-hosted-form"></div>

<script>
  import * as Purse from "https://cdn.purse-sandbox.com/headless-checkout/latest/purse.esm.js";

  // initialize the checkout
  const checkout = await Purse.createHeadlessCheckout("client-session-data");

  // get a reference to the form
  const form = document.getElementById("purse-hosted-form");
</script>

3. Render the Hosted Form​

Subscribe to available payment methods and render the Hosted Form:

// subscribe to available payment methods
checkout.paymentMethods.subscribe((paymentMethods) => {
    const creditCard = paymentMethods.find((m) => m.method === "creditcard");

    if (creditCard) {
        form.innerHTML = "";
        // render the Hosted Form
        creditCard.getPaymentElement({
            hostedForm: {
                panInputLabel: "Card number",
                panPlaceholder: "•••• •••• •••• ••••",
                cvvInputLabel: "Security code",
                cvvPlaceholder: "•••",
                expirationInputLabel: "Expiration date",
                expirationPlaceholder: "••/••",
                holderInputLabel: "Cardholder name",
                holderPlaceholder: "John Doe"
            }
        }).appendTo("purse-hosted-form");
    }
});

💡 You can localize labels and placeholders using the hostedForm config options.

4. Customize the look and feel​

The Hosted Form supports various customization options including:

  • Input labels
  • Error messages
  • Fonts and colors

Refer to the Customization Guide for a full list of supported options.

Summary​

The Hosted Form is ideal when you want:

  • A quick and secure way to accept card payments
  • Minimal PCI compliance burden
  • UI flexibility without full custom rendering