Take payments
Harbour Tickets
Events with sessions, ticket classes, early-bird prices, approval tickets, attendee data done right, and QR check-in.
Harbour Tickets is an app the business switches on in Apps. Events have ticket types (paid or
free, some needing the organiser's approval), an attendee form, and a page at
pay.harbour.africa/e/evt_…. Tickets are paid through Harbour Checkout into the business's own provider
account, and each comes with a QR code that checks in once at the door.
Ticket categories, sessions and seats
Each ticket type has a class (Regular, VIP, VVIP, Early bird, Student, Table, or the business's own name), a price and a number of seats. An event that runs more than once, such as a 4:00 pm and a 6:00 pm show, gives each type its session (a name and a start time within the event): add one ticket type per class per session, so two shows with Regular, VIP and VVIP are six ticket types. Left empty, a type's name is made from its class and session, such as "VIP · 6:00 pm show". The event page and the API group tickets by session, then list them by price, and a buyer can mix sessions and classes in one order. Each type can also have its own on-sale window, a most-per-order limit and an approval step. The organiser adds a banner (2:1) and a thumbnail (square) to each event. Harbour resizes and compresses them and serves a smaller copy to phones.
Early-bird pricing
Any paid ticket type can have an early-bird price: a lower price that applies until a date, for the first so many seats, or both, whichever runs out first. After that the regular price applies by itself. The event page shows the early-bird price beside the struck-out regular price, with when it ends and how many are left at it. Early-bird seats held by an unpaid order come back when the hold lapses.
An order that crosses the limit is split: with 2 early-bird seats left, 3 Regular tickets are 2 at the early-bird
price and 1 at the regular price, as two lines on the order and its invoice (the early-bird line is marked
"(Early bird)" and "price_tier": "early"). In the API, each ticket type's price_now_minor is
what a buyer pays right now; show it rather than price_minor, and always charge from the order Harbour
returns, never from your own sum.
Several showings: duplicate and tag
One event can have several sessions, each with its own ticket types. When each showing should be an event of its own (its own date, page, seats and badge), make the first one and use Duplicate on its page. The copy is a draft with the same details, pictures, attendee form and ticket types (prices, seats and early-bird prices), with nothing sold. Change its date, time and tags, then publish it.
Tags tell showings apart: up to five short labels per event, such as 4PM Show and
Evening Show for the 4:00 pm showing of Princess Inikpi, and 8PM Show and
Late Night Show for the 8:00 pm one. They are on the event page and in the API as tags, so
your website can show them as a badge on the poster.
Picture shapes
Choose the shape the banner and the thumbnail are cropped to, so they match how your website shows events: the
banner 2:1 (the default), 16:9, 3:2, 4:3, 1:1, 4:5 or 3:4, and the thumbnail 1:1 (the default), 4:3, 3:4, 4:5 or 16:9.
A new shape applies to the next picture uploaded. The API gives the shapes as banner_shape and
thumbnail_shape.
Deleting events
An event that never took an order or a registration can be deleted from its page, with its ticket types, form
and pictures; Delete drafts on the events list removes every such draft at once. Deleting one that was
on sale sends event.deleted. An event with orders is kept as a record: cancel it instead.
For a business's own website, each event also has a web address name (slug, unique in the business,
made from the name when left empty), the venue's street address, and an optional formatted description in HTML.
Harbour keeps paragraphs, headings, bold, italics, lists and links, and removes anything else before saving.
Booking and approvals
Standard tickets go straight to payment. A ticket type marked "needs approval" is booked as a registration; the
organiser approves or declines it in the dashboard (or with POST /v1/registrations/{id}/approve), and an
approved attendee gets a link to pay. A paid order issues one ticket per seat and emails them.
Every purchase also gets an invoice, numbered with the business's invoices. Its link pays the same order while the seats are held; it is marked paid when the order is paid, and void if the seats lapse unpaid.
The buyer gets their tickets by email in the organiser's colours: the event's banner, the organiser's logo, and a card per ticket with its class, session, QR code and printed code. The tickets are also attached as a PDF, a page each, and every ticket page has Download PDF.
Attendee data, NDPA and GDPR
Every question on the attendee form states why it is asked, and attendees see it. Questions about health, religion, ethnicity or ID numbers are sensitive: the organiser must give a lawful basis, and the attendee must tick explicit consent. Answers are stored encrypted and deleted after the event's retention period (90 days by default); the ticket and payment records stay. Exports of attendee data are logged.
At the door
The QR code holds the ticket code and a signature, never the attendee's name. The dashboard's scanner reads it with the phone camera where the browser can, or takes the 12-character code typed in, and works offline from a downloaded list (code hashes and status only) that syncs when the connection is back.
For gate staff without a Harbour account, the organiser makes a door link on the event's page. It opens the same scanner on any phone, checks tickets in for that event only, works until a day after the event ends, and can be replaced or turned off at any time. Your own scanner can use the API:
curl -s -X POST https://api.harbour.africa/v1/events/evt_…/check-in \
On your website
The quickest way: the widget shows the date, the place and the ticket types, and "Get tickets" opens the event page in a new tab.
<script src="https://pay.harbour.africa/v1/harbour.js" data-key="hb_pk_live_…" async></script>
<div data-harbour="tickets" data-event="evt_…"></div>
Selling from your own pages
To keep buyers on your own site, sell through the API from your server with a secret key. Harbour holds the seats, takes the payment into your provider account, issues the tickets and the invoice, and tells your server by webhook. You never handle card details and never keep your own ticket stock.
1. List the events and their tickets.
PHP
<?php
// harbour($method, $path, $body, idempotencyKey:) stands for your HTTP call with the secret key, or the PHP SDK.
// Your server lists what is on sale. The secret key stays on the server; never put it in a page.
$events = harbour('GET', '/v1/events?status=published&upcoming=1')['data'];
foreach ($events as $e) {
// $e['name'], $e['tags'] (["4PM Show", "Evening Show"]), $e['starts_at'], $e['venue'], $e['refund_policy'],
// $e['banner_url'] and $e['thumbnail_url'] (cropped to $e['banner_shape'] and $e['thumbnail_shape'], such as "4:3")
foreach ($e['ticket_types'] as $t) {
// $t['id'] (tt_…), $t['class'] (Regular, VVIP…), $t['session'] ("4:00 pm show"), $t['session_starts_at'],
// $t['price_minor'] (the regular price), $t['price_now_minor'] (what a buyer pays right now),
// $t['early_bird'] (null, or { price_minor, ends_at, limit, active, left }),
// $t['available'] (seats left, null if unlimited), $t['max_per_order'], $t['on_sale']
}
// group $e['ticket_types'] by $t['session'] for a show that runs more than once: they come in session order
// $e['form']: the organiser's questions, each with its purpose; sensitive ones need the buyer's consent
}
2. Create the order and send the buyer to pay. Use an idempotency key so a double click never makes two orders.
PHP
<?php
// The buyer chose their tickets on your page and pressed Pay. Seats are held for 15 minutes.
$order = harbour('POST', '/v1/events/' . $eventId . '/orders', [
'tickets' => [['type' => 'tt_01k5…', 'quantity' => 2]],
'customer' => ['name' => 'Funke Adeyemi', 'email' => 'funke@example.ng', 'phone' => '+234 803 123 4567'],
'answers' => ['412' => 'Adeyemi Events'], // form field id => answer
'consents' => [], // form field id => true, for sensitive fields
'marketing_consent' => false, // only true if the buyer ticked it
'return_url' => 'https://yoursite.ng/tickets/status', // where the buyer lands after paying
], idempotencyKey: $yourOrderReference);
// 201: send the buyer to pay. Keep $order['id'] (ord_…) with your own order.
header('Location: ' . $order['checkout_url']);
// $order['invoice']: { number: "INV-0042", url, pdf_url } – the invoice for this purchase. Its link pays the same
// order while the seats are held, and closes once it is paid.
// 202 instead (object "registration") when the ticket needs the organiser's approval: the buyer is emailed a link.
3. Show the tickets. When order.paid and ticket.issued arrive (or when your
status page reads the order), show each ticket's QR picture from qr_url (or draw it from the qr
value), and link to its page (url) and PDF (pdf_url). Harbour emails the buyer their tickets,
so your site does not have to.
4. Keep listings in step. event.published, event.updated and
event.cancelled tell your server when to refresh. Read one event by its web address with
GET /v1/events?slug=ayinla-the-musical.
GET /v1/orders/ord_01k5…
{
"object": "order", "id": "ord_01k5…", "status": "paid", "total_minor": 10000000, "currency": "NGN",
"event": "evt_01k5…",
"lines": [
{ "name": "Regular · 4:00 pm show (Early bird)", "quantity": 2, "unit_amount_minor": 750000, "price_tier": "early" },
{ "name": "Regular · 4:00 pm show", "quantity": 1, "unit_amount_minor": 1000000, "price_tier": null },
{ "name": "VVIP · 8:00 pm show", "quantity": 1, "unit_amount_minor": 7250000, "price_tier": null }
],
"invoice": { "number": "INV-0042", "status": "paid", "url": "https://pay.harbour.africa/i/it_…" },
"tickets": [
{ "id": "tkt_…", "code": "A1B2C3D4E5F6", "qr": "HBT1.A1B2C3D4E5F6.9f3c1a2b7d",
"url": "https://pay.harbour.africa/t/tk_…", "qr_url": "https://pay.harbour.africa/t/tk_…/qr.png",
"pdf_url": "https://pay.harbour.africa/t/tk_…/pdf", "status": "valid",
"order": "ord_01k5…", "type": { "id": "tt_01k5…", "name": "Regular · 4:00 pm show", "class": "Regular", "session": "4:00 pm show" },
"attendee": { "name": "Funke Adeyemi (1 of 4)" } }
]
}
Errors come back as usual: sold out, too many in one order, a ticket not for this event, a missing answer or consent. The message is written for the buyer, so you can show it as it is.
Webhooks
registration.submitted, registration.approved, registration.declined,
order.paid (with "app": "tickets"), ticket.issued, ticket.checked_in,
event.published, event.updated, event.cancelled and event.deleted.
See the events.