Skip to main content

Getting Started

Overview​

This guide walks you through the essential steps to build a fully functional Headless Checkout integration using the Purse SDK. Here is a high-level overview of the steps involved:

  1. Load the SDK : Include the script or import the module into your application.
  2. Initialize the Checkout : Use your API credentials or client session data to set up the checkout instance.
  3. Display Available Payment Methods : Dynamically list the payment methods retrieved from the SDK.
  4. Handle Method Selection : Render the appropriate form UI when a user selects a method.
  5. Validate and Submit Payment : Monitor form validity and handle the final submission.
Scope of This Guide

This guide focuses on primary payment methods (e.g. credit cards and digital wallets for example). To handle secondary methods like gift cards, see the Gift Cards guide.

Step 1 - Load the SDK​

<!-- Sandbox -->
<script src="https://cdn.purse-sandbox.com/headless-checkout/latest/purse.umd.js"></script>
<!-- Production -->
<script src="https://cdn.purse-secure.com/headless-checkout/stable/purse.umd.js"></script>

Step 2 - Initialize the Checkout​

Pass the widget.data from the client session to the createHeadlessCheckout function.

const checkout = await Purse.createHeadlessCheckout(clientSession.widget.data);

API V1 (legacy)​

Or the PurseHeadlessCheckoutV1Params object with a paymentSession

const checkout = await Purse.createHeadlessCheckout({
  apiKey: "YOUR_API_KEY",
  entityId: "YOUR_ENTITY_ID",
  environment: "sandbox",
  paymentSession: "YOUR_SESSION"
});

Step 3 - Display Payment Methods​

Let's create a simple UI to display the available payment methods.

HTML Structure​

Let's create a simple UI to display the available payment methods.

<div id="root">
    <!-- Payment methods list -->
    <ul id="methods"></ul>
    <!-- Payment form -->
    <div id="form"></div>
    <!-- Pay button -->
    <button id="pay-button" disabled>Pay</button>
</div>

Retrieve and display the Payment Methods​

Once the SDK is initialized, you can retrieve and display all available payment methods using the checkout.paymentMethods.subscribe() function.

const checkout = await Purse.createHeadlessCheckout(clientSession.widget.data);

function displayPaymentMethods(methods) {
  const ul = document.getElementById("methods");
  ul.innerHTML = "";
  methods.forEach((pm) => {
    const li = document.createElement("li");
    li.textContent = pm.partner + " - " + pm.method;
    ul.appendChild(li);
  });
}

checkout.paymentMethods.subscribe(displayPaymentMethods);

Step 4 - Select and Render a Payment Method​

Once the list of available payment methods is displayed, you'll need to handle the user selection and render the corresponding payment form.

This is done by attaching an event handler to each method. When selected, the corresponding PaymentElement will be created and mounted inside your container (e.g., a <div id="form">).

Already know which method to render?

If your integration only renders a single, known method (e.g. always credit card), skip the paymentMethods → find step and call checkout.getPaymentElement({ partner, method, hostedForm }) directly. See Hosted Form and Hosted Fields.

Example

// Add configuration (optional)
const paymentConfig = {
  hostedForm: {
    global: {
      color: "#FF0000",
      fontSize: "16px",
      fontFamily: "Arial, sans-serif"
    }
  }
};

// Add selection handler to render the chosen payment form
function handlePaymentMethodSelect(paymentMethod) {
  const form = document.getElementById("form");
  form.innerHTML = "";
  
  // Check if method is disabled before rendering
  if (paymentMethod.disabled.value) {
    const disabledReason = paymentMethod.disabled.value;
    form.innerHTML = `<p>This payment method is currently unavailable: ${disabledReason.code}</p>`;
    return;
  }
  
  const partnerUI = paymentMethod.getPaymentElement(paymentConfig);
  try {
    partnerUI.appendTo(form);
  } catch (error) {
    if (error.code === 'METHOD_DISABLED') {
      form.innerHTML = `<p>This payment method is currently unavailable.</p>`;
    } else {
      console.error('Failed to render payment method:', error);
    }
  }
}

// Update the previous displayPaymentMethods to attach click listeners
function displayPaymentMethods(methods) {
  const ul = document.getElementById("methods");
  ul.innerHTML = "";
  methods.forEach((pm) => {
    const li = document.createElement("li");
    li.textContent = `${pm.partner} - ${pm.method}`;
    li.addEventListener("click", () => handlePaymentMethodSelect(pm));
    ul.appendChild(li);
  });
}

Deselect a Payment Method​

To deselect a payment method, simply call the remove() method on the PaymentElement instance. This will automatically deselect the method and clear its split from the payment.

Automatic Cleanup

Calling remove() on a payment element automatically clears the payment split

function deselectPaymentMethod() {
    // given you have a reference to the selected PaymentElement
    selectedPaymentElement.remove();
    // Payment split is automatically cleared
}

Step 5 - Validate and Submit Payment​

To ensure the payment form is complete before submission, use checkout.isPaymentFulfilled. This reactive variable tells you when the payment form is valid and complete.

checkout.isPaymentFulfilled.subscribe((isReady) => {
    document.getElementById("pay-button").disabled = !isReady;
});

document.getElementById("pay-button").addEventListener("click", async () => {
    try {
        await checkout.submitPayment();
    } catch (error) {
        console.error(error);
    }
});
Information
Your basic Headless Checkout is now operational!

Interactive Demo​

Loading demo…

Where to go from here​