Eventro Platform API

Authentication & API Keys

Every API request must include an HTTP Authorization header containing your integration secret token. Organization tokens begin with an environment prefix:

• evt_live_...: Live production mode (charges real cards via Paystack).
• evt_test_...: Test / sandbox mode (allows simulation without payment gateways).

Permission Scopes

Integrations can be restricted to minimal scopes to protect attendee data:

Idempotency & Replays

All mutating endpoints (POST /registrations, POST /payment) support the Idempotency-Key header. Sending the same key within 24 hours replays the exact original response without duplicate charges or duplicate inventory reservations:

Rate Limits

API endpoints enforce per-minute sliding limits and daily quotas. Every response includes rate-limit headers:

Error Handling

Errors always return standard HTTP error status codes with structured JSON bodies:

Events Management

Complete lifecycle operations for creating, drafting, publishing, cancelling, and duplicating events:

Public Events (Catalog)

Unauthenticated, high-performance cached endpoints for public websites, apps, and ticket widgets. Caller keys are not required.

Ticket Types & Inventory

Configure admission categories (paid, free, donation), set sales windows, enforce min/max order quantity, and monitor real-time availability.

Orders & Registrations

Reserve tickets and manage attendee registration data. Registrations use a two-step checkout model to prevent overselling:

Attendee Check-In & Admission QR

Eventro automatically generates secure barcodes and SVG QR graphics for confirmed attendees, fully compatible with the Eventro onsite ticket scanner.

Server-Authoritative Paystack Checkout

Ticket pricing and fees are strictly calculated on Eventro servers. Third-party clients never submit raw prices.

1. Reserve Order: POST /api/v1/events/:event_id/registrations creates a pending reservation and locks inventory for 15 minutes.
2. Initialize Payment: POST /api/v1/registrations/:id/payment returns a Paystack authorization URL:
   {
     "object": "payment_session",
     "authorization_url": "https://checkout.paystack.com/access_code_123",
     "reference": "TXN-8B2F..."
   }
3. Verify Confirmation: Once the customer completes checkout on Paystack, call POST /api/v1/registrations/:id/payment/verify to confirm the transaction and issue tickets.

Test Mode & Simulation

Events created with sandbox: true allow developers to test complete booking flows without contacting live payment processors:

Response Shapes & Conventions

• Money: all amounts are JSON numbers in the main currency unit (2500.0 = NGN 2,500.00, not kobo). currency is always "NGN".
• Lists: {"object":"list","data":[...],"meta":{"page","per_page","total_count","total_pages","has_more"}}. Pagination is also in the X-Total-Count and Link headers.
• Public event page: use the event's url field (shaped https://eventro.africa/events/<id>-<slug>); don't build it yourself.
• Request bodies are wrapped under event, ticket_type or registration.

Ticket type

{
  "id": "tkt_abc123", "object": "ticket_type", "type": "paid",
  "name": "Regular", "price": 2500.0, "currency": "NGN",
  "effective_price": 2500.0, "early_bird_active": false,
  "quantity": 100, "remaining": 87, "sold_out": false, "on_sale": true,
  "sale_starts_at": null, "sale_ends_at": "2026-12-01T18:00:00Z",
  "min_per_order": 1, "max_per_order": 10,
  "enabled": true, "archived": false, "event_id": "evt_abc",
  "inventory": { "total": 100, "sold": 10, "reserved": 3, "remaining": 87 }
}

Registration (order)

{
  "id": "reg_abc123", "object": "registration",
  "event_id": "evt_abc", "ticket_type_id": "tkt_abc123",
  "status": "pending_payment", "payment_status": "unpaid", "quantity": 1,
  "amount": { "subtotal": 2500.0, "fees": 125.0, "total": 2625.0, "currency": "NGN" },
  "payment_reference": null, "ticket_code": null,
  "checked_in": false, "expires_at": "2026-10-15T10:30:00Z",
  "attendee": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": null },
  "payment_required": true,
  "next_action": "POST /api/v1/registrations/reg_abc123/payment"
}

The last two fields appear only in the create response. attendee is omitted for keys without PII access.

Webhooks & Event Delivery

Receive real-time signed HTTP POST notifications whenever events, tickets, registrations, or payments change.

Supported Event Types

Payload Format

Each delivery is a JSON POST with headers Eventro-Event-Id, Eventro-Event-Type, Eventro-Delivery-Id and Eventro-Delivery-Attempt. The envelope id is identical across retries and redeliveries, so use it to de-duplicate. Payloads are deliberately minimal (no attendee personal data); fetch details through the API with the ids provided.

{
  "id": "whevt_abc123",
  "type": "payment.succeeded",
  "api_version": "v1",
  "created_at": "2026-10-15T10:20:00Z",
  "livemode": false,
  "data": {
    "object": {
      "id": "reg_abc123", "object": "registration",
      "event_id": "evt_abc", "ticket_type_id": "tkt_abc123",
      "status": "confirmed", "payment_status": "paid", "quantity": 1,
      "amount": 2625.0, "currency": "NGN",
      "payment_reference": "ref_123", "ticket_code": "A1B2C3",
      "checked_in": false
    }
  }
}

Registration objects here use a flat amount (total, main currency unit), unlike the nested amount in the API object. ticket_code is only present on ticket.* and payment.succeeded. Event and ticket_type events carry data.object with "object": "event" / "ticket_type".

Verifying Webhook Signatures

Every webhook delivery includes the Eventro-Signature header formatted as t=<timestamp>,v1=<signature>. Calculate the HMAC-SHA256 signature using your endpoint's signing secret and verify it matches within 5 minutes: