Integration guide

Sell tickets for an event managed on your own website

Your developer can create a private Naija Tickets backing event from your website’s server. It uses the normal inventory, payment, QR and entry system but never appears in the Naija Tickets public event catalogue.

1. Create a connection and a narrowly scoped key

In Developers & Integrations, register your website’s exact origin and create a server key with external_events:write. Add checkout:write and orders:read if the same server will start and verify purchases. Assigning ordinary Naija Tickets events remains useful for events that were created inside Naija Tickets; external events are automatically assigned to the application that creates them.

This is a developer integration, not a browser feature. Do not put the secret key, event-creation request or price rules in JavaScript sent to customers.

2. Create or update the external event from your server

Use a stable external ID from your own system, such as event_2026_lagos. Repeating the same request updates that one private backing event rather than creating a duplicate. Tickets need their own stable external IDs. Prices are in NGN kobo: ₦45,000 is 4500000.

await fetch(`${process.env.NT_API_BASE}/api/v1/external-events/event_2026_lagos`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Lagos Design Night",
    description: "An evening of talks and music.",
    venue_name: "Freedom Park",
    address: "1 Hospital Road",
    city: "Lagos", state: "Lagos", timezone: "Africa/Lagos",
    starts_at: "2026-12-12T18:00:00+01:00",
    ends_at: "2026-12-12T23:00:00+01:00",
    tickets: [{
      external_id: "general", name: "General admission",
      price_kobo: 4500000, quantity: 100, admissions_per_ticket: 1,
    }],
  }),
});

3. Embed selection and complete payment

The successful response contains id: this is the backing event UUID for the public widget snippet or checkout-session API. Enable Embedded ticket checkout in the organiser connection, select the event and copy its snippet to your external page. The customer chooses tickets in the embedded frame; payment opens in a secure Naija Tickets popup so the external website never handles card details.

On verified payment, the popup closes and the loader dispatches naijaTicketsCheckoutComplete on the host page. The event contains only sessionId, status and environment. Send the session ID to your server and use orders:read before displaying a final order confirmation. This avoids trusting a browser message as payment proof.

window.addEventListener("naijaTicketsCheckoutComplete", async (event) => {
  const { sessionId, status } = event.detail;
  if (status !== "paid") return;
  // Call YOUR server. It verifies this session with Naija Tickets using orders:read.
  await fetch(`/api/tickets/confirm?session=${encodeURIComponent(sessionId)}`);
});

4. Keep updates safe

Changing a ticket price or people-admitted count is refused after an order exists. Reducing capacity below sold or currently reserved admissions is also refused. Remove a ticket from a later update to stop new sales; existing orders and tickets remain intact.

Naija Tickets verifies availability, fees, payment and ticket issuance on its server. Use signed webhooks or an orders:read status check for your own database, never a client-side price or success screen.