Intégration HTML/JS
Ajoutez le module de paiement Cardencer à n'importe quel site web en HTML et JavaScript natifs.
Ce guide ajoute le formulaire de paiement à une page HTML simple. Il fonctionne avec tout framework qui génère du HTML.
Avant de commencer, configurez votre serveur pour que POST /create-payment renvoie un clientSecret.
1. Chargez le SDK#
Ajoutez le loader à votre page de paiement, dans la fenêtre principale :
<script src="https://sdk.cardencer.com/web/0.131.0/v1/HyperLoader.js"></script>2. Ajoutez le formulaire de paiement#
Ajoutez un conteneur vide dans lequel le SDK insérera son iframe sécurisée, un bouton de paiement et une zone de message :
<form id="payment-form">
<div id="payment-element"></div>
<button id="submit" type="submit">Payer</button>
<div id="payment-message" hidden></div>
</form>3. Initialisez le SDK et montez le formulaire#
const hyper = window.Hyper(
{ publishableKey: "pk_snd_REPLACE_WITH_YOUR_KEY", profileId: "pro_REPLACE_WITH_YOUR_PROFILE_ID" },
{ customBackendUrl: "https://sandbox.cardencer.com" }, // à omettre en 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();Le formulaire affiche les moyens de paiement activés sur votre compte. walletReturnUrl est l'adresse vers laquelle Apple Pay et Google Pay redirigent après le paiement.
4. Confirmez le paiement#
Appelez confirmPayment() à la soumission du formulaire :
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", // ou "always"
});
if (error) {
message.textContent = error.message ?? "Votre paiement n'a pas pu aboutir. Veuillez réessayer.";
message.hidden = false;
document.getElementById("submit").disabled = false;
} else if (status) {
window.location.href = "/checkout/complete";
}
});Si la carte nécessite 3D Secure, le SDK affiche l'authentification. Les erreurs immédiates, comme un refus de carte, sont renvoyées dans error : affichez le message pour que le client puisse essayer une autre carte.
Pour que le SDK affiche son propre bouton de paiement, transmettez sdkHandleConfirmPayment lors de la création de l'élément :
const paymentElement = widgets.create("payment", {
sdkHandleConfirmPayment: {
handleConfirm: true,
buttonText: "Payer 49,00 €",
confirmParams: { return_url: "https://example.com/checkout/complete" },
},
});5. Affichez le résultat#
Après une redirection, le SDK ajoute payment_intent_client_secret à votre return_url. Utilisez-le pour afficher le statut :
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("Paiement réussi. Merci !");
break;
case "processing":
showMessage("Votre paiement est en cours de traitement.");
break;
case "requires_payment_method":
showMessage("Votre paiement n'a pas abouti. Veuillez essayer avec une autre carte.");
break;
default:
showMessage("Une erreur s'est produite.");
}
}Le statut affiché dans le navigateur n'a qu'une valeur informative. Ne traitez la commande qu'après confirmation de succeeded par votre serveur, via un webhook ou GET /payments/{payment_id}.
Écoutez les événements du formulaire#
Le payment element émet les événements ready, change, focus et 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;
});Testez#
Utilisez 4242 4242 4242 4242 avec n'importe quelle date future et n'importe quel CVC, et 4000 0038 0000 0446 pour déclencher une authentification 3D Secure. Consultez Environnement de test et cartes de test.
Étape suivante : personnalisez le formulaire.