Integration guide

Hosted Checkout

Keep one reservation and payment engine. Your server supplies ticket choices; authoritative prices, fees, capacity and payment verification remain on Naija Tickets.

Hosted Checkout Link · no programming

In your organiser workspace, open Developers & Integrations, create/select an application, register your website origin and assign the event. Choose your website location and purchase mode above, then select the event and return page and create the checkout link. Copy the link or HTML Buy Tickets button. No API key is needed for this method.

A public event link opens a fresh private checkout session. Buyers select tickets, enter their details, pay and see their tickets on a standalone Naija Tickets page. Disable a link to block new and unpaid checkouts. Paid tickets and refunds keep their normal rules.

<a href="https://YOUR_NAIJA_HOST/checkout/link/YOUR_PUBLIC_LINK_ID">Buy Tickets</a>

Hosted Checkout API · create a purchase intent

POST with checkout:write and a stable Idempotency-Key (8–128 letters/numbers/dots/underscores/hyphens). The same normalized request/key recovers the same session; a different request with that key conflicts.

Send the event UUID. Optional items contains ticket-type UUIDs and package quantities; omit it to let the buyer choose on the hosted page. Optional customer may prefill email/name/phone, and external_reference is a short reference for your own system. Never send price, amount, ownership/customer IDs or attendee records. Return/cancel URLs must use a registered origin plus a simple path, without query, fragment, credentials or escaped paths. Creation does not hold inventory.

const response = await fetch(`${process.env.NT_API_BASE}/api/v1/checkout-sessions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": purchaseIntentId,
  },
  body: JSON.stringify({
    event_id: eventId,
    items: [{ ticket_type_id: ticketTypeId, quantity: 2 }],
    return_url: "https://partner.example/complete",
    cancel_url: "https://partner.example/cancel",
  }),
});
// Redirect this buyer to result.data.checkout_url.
// The checkout URL is private: do not log, cache or publish it.

Let the buyer complete checkout

The buyer sees the event artwork, organiser, current ticket choices and fees on a dedicated hosted checkout page, with no marketplace navigation. They can check out as a guest and edit their details. Ordinary tickets retain normal attendee collection; group packages use buyer plus attendee claims. Reservation counts admissions, so two Group-of-5 packages reserve ten places. Prices and availability are checked again transactionally.

Sessions last up to 30 minutes, bounded by key expiry. A reservation lasts up to ten minutes and cannot outlive its session. Use the existing cancel action for an unpaid checkout; cancellation is not a refund. Unclaimed paid group places stay sold.

Verify the result on your server

After server-verified payment, the hosted confirmation shows tickets and group links plus Return to organiser. That return contains nt_session and a bounded nt_status. Ignore that status as payment proof; query the session with orders:read. Amounts are integer NGN kobo and can be null before reservation. Ticket counts distinguish unclaimed reserved admissions from usable claimed tickets.

Failed, expired or mismatched payments do not issue usable tickets. Duplicate verified callbacks do not issue twice. An already-authorised payment can finish safely after key revocation. Email failure does not invalidate a verified paid booking.

curl "$NT_API_BASE/api/v1/checkout-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $NT_API_KEY"