Integration guide

Embed ticket selection

Copy a public snippet from the organiser dashboard. The isolated iframe selects tickets and opens secure checkout in a small Naija Tickets popup over the same external website.

Generate your snippet

Register the external website’s exact origin, assign an event, choose Test/Live and explicitly enable its widget. Enable hosted checkout separately when the deployment is ready. Copy the generated snippet. Never place an API secret in it.

<div data-naija-widget="YOUR_PUBLIC_WIDGET_ID"
     data-event="YOUR_ASSIGNED_EVENT_UUID"
     data-environment="live"></div>
<script src="https://naija-tickets.vercel.app/integrations/widget-v1.js" defer></script>

Keep the purchase secure

The frame exposes public event/ticket information only, uses exact registered ancestors and isolates host CSS. Buyer details and payments stay in the trusted Naija Tickets popup. After a verified payment, the popup closes and the host receives a naijaTicketsCheckoutComplete browser event containing only a session ID, paid status and environment. No private checkout link, attendee or QR data is sent to the parent.

The default return URL uses your page origin/path and drops queries/fragments. Optional data-return-url must be a same-origin simple URL. If you add containers dynamically, call window.__naijaWidgetV1.mount(). Use orders:read on your server to verify the browser event before showing your final confirmation. Use one Naija deployment origin per page.

Unavailable or expired selections

Sold-out/end/draft/unassigned events and unregistered embedding websites fail closed. Selection proofs expire after five minutes; refresh the widget for a fresh selection. A fallback link opens public ticket selection in a new tab.

Choose Light or Dark, a Green/Blue/Violet primary palette and Rounded or Square buttons in the snippet generator. The generated data-appearance, data-accent and data-button attributes are validated options; arbitrary CSS or scripts are never accepted. Restrictive host CSP or extra site-builder frames can block the iframe or top navigation.