Website embedding — developer guide
Put a business's HayyWorld sign-in, shop, feed and reviews on its own website — including static sites. Everything runs inside iframes served by HayyWorld, so the shopper's session and payments never touch the website's own code.
Getting started
- The business owner asks for website embedding (account menu → the business → Website embedding). HayyWorld approves it and sets the fees.
- The owner invites you as Software developer (Dashboard → Staff & delegates). Accept the invite; you'll find Developers under the business in your account menu.
- Add the business's website addresses and choose the components.
- Create a test publishable key, paste the code into the website and build it.
- Run the test (Developers → Test). When it passes and the owner has paid, HayyWorld approves live.
- Create a live publishable key and swap it in.
Components
Sign-in is always included. Add one or more of Shop, Feed and Reviews & testimonials — whichever were approved for the business.
<script src="https://www.hayyworld.com/embed/v1/hayyworld.js" async></script> <hayyworld-signin key="pk_live_…"></hayyworld-signin> <!-- always; with Shop it includes the basket badge --> <hayyworld-shop key="pk_live_…"></hayyworld-shop> <!-- products, booking, events, donations, basket --> <!-- or the Shop's parts on their own pages (all part of Shop): --> <hayyworld-shop-products key="pk_live_…"></hayyworld-shop-products> <!-- products, basket --> <hayyworld-bookings key="pk_live_…"></hayyworld-bookings> <!-- classes and appointments to book --> <hayyworld-classes key="pk_live_…"></hayyworld-classes> <!-- classes only (timetable) --> <hayyworld-appointments key="pk_live_…"></hayyworld-appointments> <!-- appointments only (day and time) --> <hayyworld-events key="pk_live_…"></hayyworld-events> <!-- event tickets --> <hayyworld-donations key="pk_live_…"></hayyworld-donations> <!-- donate, basket --> <hayyworld-quick-donate key="pk_live_…" more="/donate"></hayyworld-quick-donate> <!-- appeals to fit its space; more = your donate page --> <hayyworld-for-you key="pk_live_…" more="/shop"></hayyworld-for-you> <!-- the shopper's own picks (about 5); more = your shop page --> <hayyworld-spotlight key="pk_live_…"></hayyworld-spotlight> <!-- what you chose in Dashboard › Page › Spotlight --> <hayyworld-feed key="pk_live_…"></hayyworld-feed> <hayyworld-reviews key="pk_live_…"></hayyworld-reviews>
- Each component sizes itself to its content. Put it where you want it to appear.
- The Shop can go on one page, or its parts on their own pages — say a Classes page with
<hayyworld-classes>, a Book-an-appointment page with<hayyworld-appointments>(or both on one page with<hayyworld-bookings>) and a Donate page with<hayyworld-donations>. They're all part of the Shop (one price) and share the shopper's basket; the basket badge opens it in the whole Shop or the products part on the page.<hayyworld-for-you>is just for the shopper: their last order, usual items and previous orders to add again, and what's popular here — a new shopper sees what's popular only — about 5 items, then "Show more in the shop" (your page inmore, else your HayyWorld page).<hayyworld-quick-donate>fits its space: more columns when it's wide, and as many rows as fit if you give the tag a height (for examplestyle="display:block;height:320px", orheight:100%inside a box with a height) — and fills that height; 3 rows otherwise.<hayyworld-spotlight>shows what you set up in Dashboard › Page › Spotlight — hand-picked, popular, one category or a mix of your items, and the time and opening hours, weather and Tube status if you turned them on. - With Shop on,
<hayyworld-signin>shows the basket badge beside the sign-in button — put it in your header. Clicking the badge opens the basket of the<hayyworld-shop>on the same page. (The older separate<hayyworld-shop-badge>still works but isn't needed.) - If a page has components but no
<hayyworld-signin>, the loader adds one before the first component. - Checkout happens on your page: HayyWorld's basket opens over it, with the same options as on HayyWorld (collection or delivery, promo codes, Gift Aid, ways to pay). Paying goes to the payment page (Stripe, the bank or PayPal) in the same tab, then straight back to your page. Booking and event tickets open in a HayyWorld window (a new tab on phones). You don't need to set anything up with Stripe — all payment addresses are HayyWorld's.
- Each component shows the HayyWorld and business logos, linking to the business's page on HayyWorld. They can't be hidden or restyled.
- Look: by default each component takes your website's own colours where it sits — the text colour, the background behind it and your link colour as the main colour (a pair that would be hard to read falls back to HayyWorld's). Colours, font and corners set on the Developers page override those, and a
themeattribute on a tag overrides both (colours as#rrggbb, radius0–99px). The Shop's products show as a grid of cards or as a list with images — set it on the Developers page, or per tag withtheme='{"layout":"list"}'. Checkout always keeps HayyWorld's look.
<hayyworld-shop key="pk_live_…" theme='{"primary":"#0b6e4f","radius":"8px"}'></hayyworld-shop>Keys
- Publishable (
pk_test_…,pk_live_…): for web pages. They only work on the business's allowed websites — browsers refuse to show the components anywhere else. - Secret (
sk_test_…,sk_live_…): for your server only. Never put one in a web page or an app. - Test keys work while the business is approved, including on
http://localhost. Test checkouts are priced and checked but simulated: nothing is charged, no order is made. Live keys exist once HayyWorld has approved live, and only work onhttps://websites. - Rotating a key makes a new one; the old one keeps working for 24 hours. Revoking stops a key at once. Secret keys are shown once — the owner (any key) and the developer who made it can reveal it again after confirming a code sent by email.
Testing and going live
Live websites only ever get a configuration that has passed a test. Start a test on the Developers page, then on the website, with the test key:
- open every page with components, on every allowed website;
- sign in;
- Shop: add something and complete the test payment · Feed: like or reply to a post · Reviews: open them;
- sign out;
- then press Check results.
Webhooks set up for test get a signed test.ping during the check, and must answer with a 2xx. Any error the components report fails the test.
After going live, any change — a website, a component, webhooks — needs the full test again; a change to the look only needs the quick check (components load, no errors). Once it passes, publish it to live yourself. Until then the live website keeps the last tested configuration.
Secret-key API
For your server. Send the secret key as a bearer token. Every answer is { ok: true, data } or { ok: false, error: { code, message } }. 120 requests a minute per key. Full schema: API reference (tag business-api).
curl https://www.hayyworld.com/api/v1/business/orders?limit=20 \ -H "Authorization: Bearer sk_live_…"
| GET /api/v1/business/me | Which business and mode the key is for |
| GET /api/v1/business/products | Products, services and donation items |
| POST /api/v1/business/products/stock | Set stock_quantity and/or is_available (test keys: simulated) |
| GET /api/v1/business/orders?since=&limit= | Recent orders with items |
| GET /api/v1/business/orders/item?id= | One order |
| GET /api/v1/business/bookings?since=&limit= | Recent bookings |
| GET /api/v1/business/events | Upcoming events |
Customers' contact details stay on HayyWorld. Products are created and edited on the business's dashboard.
Webhooks
Add an https address on the Developers page and choose events: order.paid, order.refunded, booking.created, booking.cancelled, ticket.issued, donation.succeeded, donation.regular.cancelled, product.stock_low. Each delivery is a POST with JSON:
{ "id": "evt_…", "type": "order.paid", "created": 1760000000,
"livemode": true, "business_id": "…", "data": { "order": { … }, "items": [ … ] } }Check the HayyWorld-Signature header (t=…,v1=…) with the endpoint's signing secret, and reject anything older than 5 minutes:
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}Answer with a 2xx quickly. Events are retried with backoff for 3 days (use HayyWorld-Event-Id to ignore repeats); after that the address is turned off and the owner and developers are emailed. Turn it back on and resend from the delivery log.
Website QR
Once the Shop is live, set the website shop page on the Developers page. The business can then download a QR that opens it. The QR points to HayyWorld and is forwarded at each scan, so if embedding pauses or ends, printed codes open the business's HayyWorld page instead.
Security
- Never put a secret key in a web page, app or repository. Rotate it if it leaks.
- Keep your allowed websites to the ones you use.
- Don't cover or hide the components or their logos — it's against the embedding terms.
- Every key, website, test and webhook change is in the audit log the business owner sees.
Questions? Contact us.