A drop-in payment popup with one extra superpower — the customer’s saved card lives on their phone, reusable across every Duro merchant.
The inline SDK is DuroCheckout.open() — a drop-in script that opens a payment sheet over the merchant’s own page, in an iframe, so card data never touches the merchant’s DOM. Mechanically it’s the hosted checkout flow rendered as a popup. What makes it different is the identity bar.
The sheet renders the same flow as hosted checkout, in a popup over your page. You still create the session server-side with your secret key, then hand the browser only the session token — so the amount can never be tampered with client-side.
1
Add the SDK
Drop the script onto the page with your pay button. It exposes window.DuroCheckout.
Identical to hosted checkout — your server calls POST /v1/checkout/sessions and returns just the token and id to the page. The secret key stays on the server.
Fetch a token from your server, then call DuroCheckout.open() with your publishable key. Card entry happens inside the iframe — it never touches your DOM.
document.getElementById("pay").addEventListener("click", async () => { const { token } = await fetch("/api/pay", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ planId: "plan_01HFZ8Q…", orderId: "ord_1234" }), }).then((r) => r.json()); DuroCheckout.open({ key: "pk_test_•••", // publishable key — safe in the browser token, // the session your server just created onSuccess: (reference) => { // soft confirmation — verify on your server before granting access window.location.href = `/checkout/confirming?ref=${reference}`; }, onClose: () => console.log("sheet dismissed"), onError: (err) => console.error(err), });});
4
Verify on success (server)
onSuccess fires in the browser, so confirm it server-side with the session id before acting. Source of truth, every time.
// GET /checkout/confirming → your serverasync function isCompleted(sessionId: string) { const res = await fetch( `https://api.useduro.com/v1/checkout/sessions/${sessionId}`, { headers: { Authorization: `Bearer ${process.env.DURO_SECRET_KEY}` } }, ); const { data } = await res.json(); return data.status === "completed" ? data : null;}
5
Receive the webhook
The popup can be closed before onSuccess ever runs — so the webhook is your reliable trigger. Subscribe subscription_payment_success in Developers → Webhooks and verify the signature against the raw body. (Full handler and signature check in Webhook Events.)
Both paths — the onSuccess callback and the webhook — funnel into one idempotent fulfil() that verifies, then provisions exactly once.
async function fulfil(subscriptionId: string) { const order = await orders.bySubscription(subscriptionId); if (!order || order.fulfilled) return; // idempotent const paid = await isCompleted(order.checkoutId); // verify if (!paid) return; await entitlements.grant(order.customerId, paid.planId); await orders.markFulfilled(order.id);}
onSuccess is a convenience, not a guarantee — wire the webhook and the verify call too. The browser can vanish mid-payment; the server-side pair is what actually grants access.
The “save to my phone” moment is the whole strategy
When a guest pays and ticks save to my phone, the sheet:
Sends a one-time code to their phone over the WhatsApp Cloud API.
Verifies the code.
Creates (or finds) the customer’s universal identity keyed to that phone.
Links the tokenised payment method to the identity — not to the merchant.
The next time that human checks out anywhere on Duro, the identity bar recognises the phone and offers their saved card in one tap. That’s the network effect: the saved wallet belongs to the person. See the identity chapter →
The same rail set as hosted checkout — card, direct debit, one-time bank transfer, USSD, virtual account — and the same instant rail-switch on failure (“Card didn’t go through — pay with transfer?”). For transfers, the sheet polls for confirmation; the merchant page just waits on the onSuccess callback.
