Checkout SDK overview
Embed the Cardencer checkout in your website: cards, Apple Pay and Google Pay in one secure, customisable payment form.
The Cardencer checkout SDK renders a payment form inside a Cardencer-hosted iframe on your page. Card details go straight from the customer's browser to Cardencer, so they never touch your servers and your PCI DSS scope stays at SAQ A.
The payment form:
- accepts Visa and Mastercard, plus Apple Pay and Google Pay where the device supports them,
- runs 3D Secure challenges automatically,
- shows saved cards to returning customers,
- adapts to the customer's language and can be styled to match your brand.
How it fits together#
| Step | Where | What happens |
|---|---|---|
| 1 | Your server | POST /payments with your secret key. Return the client_secret to the browser. |
| 2 | Browser | Load HyperLoader.js from sdk.cardencer.com, initialise it with your publishable key and profile ID. |
| 3 | Browser | Create the payment element with the client_secret and mount it. |
| 4 | Browser | On submit, call confirmPayment(). The SDK handles 3D Secure and redirects to your return_url. |
| 5 | Your server | Confirm the final status with a webhook or GET /payments/{payment_id}. |
Set up your server#
Your server creates the payment and hands the client_secret to the browser. Never send your secret key to the browser.
import express from "express";
const CARDENCER_API = "https://sandbox.cardencer.com"; // https://api.cardencer.com in production
const app = express();
app.use(express.json());
app.post("/create-payment", async (req, res) => {
const order = await loadOrder(req.body.orderId); // compute the amount on your server
const response = await fetch(`${CARDENCER_API}/payments`, {
method: "POST",
headers: { "api-key": process.env.CARDENCER_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
amount: order.amount,
currency: "EUR",
capture_method: "automatic",
customer_id: order.customerId,
description: `Order ${order.id}`,
return_url: "https://example.com/checkout/complete",
}),
});
const payment = await response.json();
if (payment.error) return res.status(400).json({ error: payment.error.message });
res.json({ clientSecret: payment.client_secret });
});
app.listen(4242);import os, requests
from flask import Flask, jsonify, request
CARDENCER_API = "https://sandbox.cardencer.com" # https://api.cardencer.com in production
app = Flask(__name__)
@app.post("/create-payment")
def create_payment():
order = load_order(request.json["orderId"]) # compute the amount on your server
payment = requests.post(
f"{CARDENCER_API}/payments",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
json={
"amount": order.amount,
"currency": "EUR",
"capture_method": "automatic",
"customer_id": order.customer_id,
"description": f"Order {order.id}",
"return_url": "https://example.com/checkout/complete",
},
).json()
if "error" in payment:
return jsonify(error=payment["error"]["message"]), 400
return jsonify(clientSecret=payment["client_secret"])If the basket changes after you created the payment, update it with POST /payments/{payment_id} instead of creating a new one.
Load the SDK#
Always load the loader from Cardencer; do not bundle or self-host it:
<script src="https://sdk.cardencer.com/web/0.131.0/v1/HyperLoader.js"></script>Initialise it with the publishable key and profile ID from API keys in the dashboard. In the sandbox, point customBackendUrl at the sandbox API; in production you can omit it.
const hyper = window.Hyper(
{ publishableKey: "pk_snd_REPLACE_WITH_YOUR_KEY", profileId: "pro_REPLACE_WITH_YOUR_PROFILE_ID" },
{ customBackendUrl: "https://sandbox.cardencer.com" },
);For Apple Pay, the loader must run in the top-level window of your checkout page. If you render the payment form inside your own iframe, load HyperLoader.js in the top-level window as well.
Choose your integration#
- React: React components and hooks.
- HTML/JS: plain HTML and JavaScript, any framework.
- Customization: layouts, themes, wallets and fonts.
- Error codes: what the SDK and API return when something fails.
Load faster#
Load the SDK as early as possible, ideally on the page before checkout (for example the cart page). The loader caches its assets, so the payment form appears almost instantly when the customer reaches checkout.