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:
<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:
<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#
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:
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:
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:
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:
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.