Skip to content

HTML/JS integration

Add the Cardencer checkout to any website with plain HTML and JavaScript.

This guide adds the payment form to a plain HTML page. It works with any framework that renders HTML.

Before you start, set up your server so that POST /create-payment returns a clientSecret.

1. Load the SDK#

Add the loader to your checkout page, in the top-level window:

html
<script src="https://sdk.cardencer.com/web/0.131.0/v1/HyperLoader.js"></script>

2. Add the payment form#

Add an empty container where the SDK will insert its secure iframe, a pay button and a message area:

html
<form id="payment-form">
  <div id="payment-element"></div>
  <button id="submit" type="submit">Pay now</button>
  <div id="payment-message" hidden></div>
</form>

3. Initialise the SDK and mount the form#

js
const hyper = window.Hyper(
  { publishableKey: "pk_snd_REPLACE_WITH_YOUR_KEY", profileId: "pro_REPLACE_WITH_YOUR_PROFILE_ID" },
  { customBackendUrl: "https://sandbox.cardencer.com" }, // omit in production
);
let widgets;

async function initialize() {
  const response = await fetch("/create-payment", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ orderId: "58211" }),
  });
  const { clientSecret } = await response.json();

  widgets = hyper.widgets({ clientSecret, appearance: { theme: "default" } });
  const paymentElement = widgets.create("payment", {
    layout: "tabs",
    wallets: { walletReturnUrl: "https://example.com/checkout/complete" },
  });
  paymentElement.mount("#payment-element");
}

initialize();

The form shows the payment methods enabled for your account. walletReturnUrl is where Apple Pay and Google Pay return after payment.

4. Confirm the payment#

Call confirmPayment() when the form is submitted:

js
const form = document.getElementById("payment-form");
const message = document.getElementById("payment-message");

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  document.getElementById("submit").disabled = true;

  const { error, status } = await hyper.confirmPayment({
    widgets,
    confirmParams: { return_url: "https://example.com/checkout/complete" },
    redirect: "if_required", // or "always"
  });

  if (error) {
    message.textContent = error.message ?? "Your payment could not be completed. Please try again.";
    message.hidden = false;
    document.getElementById("submit").disabled = false;
  } else if (status) {
    window.location.href = "/checkout/complete";
  }
});

If the card needs 3D Secure, the SDK shows the challenge. Immediate errors, such as a declined card, come back in error: show the message so the customer can try another card.

To let the SDK render its own pay button instead, pass sdkHandleConfirmPayment when you create the element:

js
const paymentElement = widgets.create("payment", {
  sdkHandleConfirmPayment: {
    handleConfirm: true,
    buttonText: "Pay €49.00",
    confirmParams: { return_url: "https://example.com/checkout/complete" },
  },
});

5. Show the result#

After a redirect, the SDK appends payment_intent_client_secret to your return_url. Use it to display the status:

js
async function checkStatus() {
  const clientSecret = new URLSearchParams(window.location.search).get("payment_intent_client_secret");
  if (!clientSecret) return;

  const { paymentIntent } = await hyper.retrievePaymentIntent(clientSecret);
  switch (paymentIntent.status) {
    case "succeeded":
      showMessage("Payment succeeded. Thank you!");
      break;
    case "processing":
      showMessage("Your payment is processing.");
      break;
    case "requires_payment_method":
      showMessage("Your payment was not successful. Please try another card.");
      break;
    default:
      showMessage("Something went wrong.");
  }
}

The status shown in the browser is for display only. Fulfil the order only after your server has confirmed succeeded, through a webhook or GET /payments/{payment_id}.

Listen to form events#

The payment element emits ready, change, focus and blur:

js
const paymentElement = widgets.getElement("payment");
paymentElement?.on("change", (event) => {
  // { elementType: "payment", complete: false, empty: false, value: { type: "card" } }
  document.getElementById("submit").disabled = !event.complete;
});

Test it#

Use 4242 4242 4242 4242 with any future date and any CVC, and 4000 0038 0000 0446 to see a 3D Secure challenge. See Sandbox & test cards.

Next: customise the form.