referral.axile.ng

[samkiell]

designing referral.axile.ng

Temi, we would need this backend api emdpoints, its just a rough scalfold, please work with it and enhance it, thanks

🔐 Authentication
POST /auth/register
POST /auth/login
GET /auth/me

🎟 Events
POST /events
GET /events
GET /events/{eventId}
GET /events?referralEnabled=true

🔗 Referral
GET /r/{refCode}/events/{eventId}

🎫 Ticket Purchase Webhook (Internal)
POST /webhooks/tickets/purchased

✅ Ticket Check-in Webhook (Internal)
POST /webhooks/tickets/checked-in

💰 Wallet
GET /wallet
GET /wallet/transactions

💸 Withdrawals
POST /withdrawals
GET /withdrawals

Request/Response Models:

python

Create Event Request
{
"title": "Summer Music Festival",
"price": 5000,
"referralEnabled": true,
"rewardType": "percentage", // "percentage" | "fixed"
"rewardValue": 30
}

Purchase Webhook Request (Internal)
{
"buyerId": "usr_123xyz",
"eventId": "evt_456abc",
"ticketId": "tkt_789def",
"referralCode": "SUMMER30" // Optional
}

Check-in Webhook Request (Internal)
{
"ticketId": "tkt_789def"
}

Withdrawal Request
{
"amount": 1000,
"paymentMethod": "paypal", // or "bank_transfer", "gcash", etc.
"accountDetails": {
"email": "[email protected]"
}
}
Database Schema:

sql
referrals (
id UUID PRIMARY KEY,
referrer_id UUID NOT NULL,
buyer_id UUID,
event_id UUID NOT NULL,
ticket_id UUID,
points_earned INT DEFAULT 0,
status referral_status DEFAULT 'pending', -- pending | credited | expired
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
)

[Temiloluwagboyega]

This are the endpoint we have so far, and the endpoin tht ned to be updated cause we added refeeral stuff for the

Referral (Referee) & Event Referral Rewards — Frontend Guide

This document covers referee authentication, referee-only event APIs, and organizer event fields for referral rewards. All paths are relative to your API base URL.

---

1. Two user types (do not mix tokens)

App	User	Auth
Referee app	SignUp (referree)	JWT from login/ or Google referee flow
Organizer app	Organizer + Django User	JWT from organizer auth

Referee JWT uses Django User.username = referee email. Use the correct token per screen.

---

2. Referee authentication

2.1 Email/password signup

1. POST /signup/ — Username, Firstname, Lastname, Phone (optional), Email, Password
2. POST /verify-otp/ — Email, otp → 201: user, referree_id

2.2 Login

POST /login/ — { "email", "password" } → access, refresh

Authorization: Bearer <access_token>

2.3 Google (referee)

POST /referee/google-signup/ — { "token": "<google_access_token>" } or access_token

2.4 Other

• POST /logout/ — { "refresh" }
• GET/PATCH /referee/profile/ — profile
• Password reset: /password/reset/, etc.

---

3. Referee events (use_referral: true)

Active referee JWT required (SignUp match + is_active).

Method	Path
GET	/referee/events/
GET	/referee/events/<identifier>/ (event_id or event_slug)

Reward fields (API uses 0–100 for percentage)

Field	Meaning
use_referral	Event offers referral rewards
referral_reward_type	"flat" or "percentage"
referral_reward_amount	Flat payout (currency) when type is flat
referral_reward_percentage	0–100 when type is percentage

List example

{
  "events": [{
    "event_id": "event:AB-12345",
    "event_slug": "summer-fest",
    "name": "Summer Fest",
    "event_type": "music",
    "pricing_type": "paid",
    "location": "Lagos",
    "date": "2025-06-01T18:00:00Z",
    "image": "https://...",
    "use_referral": true,
    "referral_reward_type": "percentage",
    "referral_reward_amount": null,
    "referral_reward_percentage": 7.5
  }],
  "count": 1
}

Detail adds description, max_quantity_per_booking, ticket_categories.

---

4. Organizer: referral rewards on events

POST /event/ · PATCH /events/<event_id>/update/

Field	Rules
use_referral	Boolean
referral_reward_type	If use_referral: "flat" | "percentage"
referral_reward_amount	Required for flat (positive)
referral_reward_percentage	Required for percentage: 0–100

If use_referral is false, reward fields are cleared.

GET /organizer/events/ — includes reward block above.

GET /config/ — referral_reward_types for dropdowns:

"referral_reward_types": [
  { "value": "flat", "label": "Flat amount" },
  { "value": "percentage", "label": "Percentage" }
]

---

5. Public vs referee

Endpoint	Referral reward fields
GET /events/<id>/details/	Hidden
GET /event/ (list)	Hidden
GET /referee/events/ …	Shown

---

6. Backend reference

Piece	Location
referral_reward_fields_for_api()	radar/event/models.py
Organizer serializer	radar/event/serializers.py
Referee event serializers	radar/referral_app/serializers.py

Run migrations after deploy: referral_commission_* columns renamed to referral_reward_*.

[samkiell]

We can work with this!

[samkiell]

just added it to the repo as API_DOCUMENTATION.MD.
it can be accesible thru here, Beans

[Temiloluwagboyega]

Referral (Referee) & Event Referral Rewards — Frontend Guide

This document covers referee authentication, referee-only event APIs, and organizer event fields for referral rewards. All paths are relative to your API base URL.

---

1. Two user types (do not mix tokens)

App	User	Auth
Referee app	SignUp (referree)	JWT from login/ or Google referee flow
Organizer app	Organizer + Django User	JWT from organizer auth

Referee JWT uses Django User.username = referee email. Use the correct token per screen.

---

2. Referee authentication

2.1 Email/password signup

1. POST /signup/ — Username, Firstname, Lastname, Phone (optional), Email, Password
2. POST /verify-otp/ — Email, otp → 201: user, referree_id

2.2 Login

POST /login/ — { "email", "password" } → access, refresh

Authorization: Bearer <access_token>

2.3 Google (referee)

POST /referee/google-signup/ — { "token": "<google_access_token>" } or access_token

2.4 Other

• POST /logout/ — { "refresh" }
• GET/PATCH /referee/profile/ — profile
• Password reset: /password/reset/, etc.

---

3. Referee events (use_referral: true)

Active referee JWT required (SignUp match + is_active).

Method	Path
GET	/referee/events/
GET	/referee/events/<identifier>/ (event_id or event_slug)

Reward fields (API uses 0–100 for percentage)

Field	Meaning
use_referral	Event offers referral rewards
referral_reward_type	"flat" or "percentage"
referral_reward_amount	Flat payout (currency) when type is flat
referral_reward_percentage	0–100 when type is percentage

List example

{
  "events": [{
    "event_id": "event:AB-12345",
    "event_slug": "summer-fest",
    "name": "Summer Fest",
    "event_type": "music",
    "pricing_type": "paid",
    "location": "Lagos",
    "date": "2025-06-01T18:00:00Z",
    "image": "https://...",
    "use_referral": true,
    "referral_reward_type": "percentage",
    "referral_reward_amount": null,
    "referral_reward_percentage": 7.5
  }],
  "count": 1
}

Detail adds description, max_quantity_per_booking, ticket_categories.

---

4. Organizer: referral rewards on events

POST /event/ · PATCH /events/<event_id>/update/

Field	Rules
use_referral	Boolean
referral_reward_type	If use_referral: "flat" | "percentage"
referral_reward_amount	Required for flat (positive)
referral_reward_percentage	Required for percentage: 0–100

If use_referral is false, reward fields are cleared.

GET /organizer/events/ — includes reward block above.

GET /config/ — referral_reward_types for dropdowns:

"referral_reward_types": [
  { "value": "flat", "label": "Flat amount" },
  { "value": "percentage", "label": "Percentage" }
]

---

5. Public vs referee

Endpoint	Referral reward fields
GET /events/<id>/details/	Hidden
GET /event/ (list)	Hidden
GET /referee/events/ …	Shown

---

6. Organizer referral stats endpoint

Organizer JWT required.

Method	Path	Purpose
GET	/referee/<referee_id>/<event_id>/	Stats for one referee in one event

Response fields

Field	Meaning
referral_name	Referee display name (Firstname + Lastname fallback to Username)
tickets_sold	Count of tickets sold by this referee for this event
referral_revenue	Sum of total_price for those sold tickets

How backend computes stats

Tickets are filtered by all of these:

• Ticket.event = <event_id>
• Ticket.referral = <referee_id>
• Ticket.status in ('confirmed', 'used')

Then:

• tickets_sold = count of filtered tickets
• referral_revenue = sum of filtered total_price

---

7. Unique referral registration flow

When referral is used during ticket booking:

1. Referral id is saved on each ticket as Ticket.referral.
2. On confirmation (free immediately, paid via webhook/verify-payment), backend registers that id into Event.referral_referee_ids.
3. Event.referral_referee_ids behaves like a set:
   • same referee_id is stored once per event
   • repeated sales do not duplicate it

This field is internal and not exposed in normal public event payloads.

---

8. Backend reference

Piece	Location
referral_reward_fields_for_api()	radar/event/models.py
Organizer serializer	radar/event/serializers.py
Referee event serializers	radar/referral_app/serializers.py
Referee-event stats view	radar/referral_app/views.py
Event referral set field	radar/event/models.py (referral_referee_ids)

Run migrations after deploy: referral_commission_* columns renamed to referral_reward_*.

[Temiloluwagboyega]

a new @samkiell api endpoint

[Abraham123-dev]

for the base URL : https://axile-dev-env.onrender.com

[Temiloluwagboyega]

New update @samkiell

Referral (Referee) & Event Referral Rewards — Frontend Guide

This document covers referee authentication, referee-only event APIs, and organizer event fields for referral rewards. All paths are relative to your API base URL.

---

1. Two user types (do not mix tokens)

App	User	Auth
Referee app	SignUp (referree)	JWT from login/ or Google referee flow
Organizer app	Organizer + Django User	JWT from organizer auth

Referee JWT uses Django User.username = referee email. Use the correct token per screen.

---

2. Referee authentication

2.1 Email/password signup

1. POST /signup/ — Username, Firstname, Lastname, Phone (optional), Email, Password
2. POST /verify-otp/ — Email, otp → 201: user, referree_id

2.2 Login

POST /login/ — { "email", "password" } → access, refresh

Authorization: Bearer <access_token>

2.3 Google (referee)

POST /referee/google-signup/ — { "token": "<google_access_token>" } or access_token

2.4 Other

• POST /logout/ — { "refresh" }
• GET/PATCH /referee/profile/ — profile
• Password reset: /password/reset/, etc.

---

3. Referee events (use_referral: true)

Active referee JWT required (SignUp match + is_active).

Method	Path
GET	/referee/events/
GET	/referee/events/<identifier>/ (event_id or event_slug)

Reward fields (API uses 0–100 for percentage)

Field	Meaning
use_referral	Event offers referral rewards
referral_reward_type	"flat" or "percentage"
referral_reward_amount	Flat payout (currency) when type is flat
referral_reward_percentage	0–100 when type is percentage

List example

{
  "events": [{
    "event_id": "event:AB-12345",
    "event_slug": "summer-fest",
    "name": "Summer Fest",
    "event_type": "music",
    "pricing_type": "paid",
    "location": "Lagos",
    "date": "2025-06-01T18:00:00Z",
    "image": "https://...",
    "use_referral": true,
    "referral_reward_type": "percentage",
    "referral_reward_amount": null,
    "referral_reward_percentage": 7.5
  }],
  "count": 1
}

Detail adds description, max_quantity_per_booking, ticket_categories.

---

4. Organizer: referral rewards on events

POST /event/ · PATCH /events/<event_id>/update/

Field	Rules
use_referral	Boolean
referral_reward_type	If use_referral: "flat" | "percentage"
referral_reward_amount	Required for flat (positive)
referral_reward_percentage	Required for percentage: 0–100

If use_referral is false, reward fields are cleared.

GET /organizer/events/ — includes reward block above.

GET /config/ — referral_reward_types for dropdowns:

"referral_reward_types": [
  { "value": "flat", "label": "Flat amount" },
  { "value": "percentage", "label": "Percentage" }
]

---

5. Public vs referee

Endpoint	Referral reward fields
GET /events/<id>/details/	Hidden
GET /event/ (list)	Hidden
GET /referee/events/ …	Shown

---

6. Organizer referral stats endpoint

Organizer JWT required.

Method	Path	Purpose
POST	/referee/<event_id>/	Bulk stats for referral IDs passed in body

Response fields

Field	Meaning
referral_name	Referee display name (Firstname + Lastname fallback to Username)
tickets_sold	Count of tickets sold by this referee for this event
referral_revenue	Sum of total_price for those sold tickets

How backend computes stats

Request body format:

{
  "referrals": [
    { "referee_id": "organiser:abc123" },
    { "referee_id": "organiser:def456" }
  ]
}

Tickets are filtered by all of these:

• Ticket.event = <event_id>
• Ticket.referral = <referee_id> (for each requested body item)
• Ticket.status in ('confirmed', 'used')

Then:

• tickets_sold = count of filtered tickets
• referral_revenue = sum of filtered total_price

---

7. Unique referral registration flow

When referral is used during ticket booking:

1. Referral id is saved on each ticket as Ticket.referral.
2. On confirmation (free immediately, paid via webhook/verify-payment), backend registers that id into Event.referral_referee_ids.
3. Event.referral_referee_ids behaves like a set:
   • same referee_id is stored once per event
   • repeated sales do not duplicate it

This field is internal and not exposed in normal public event payloads.

---

8. Backend reference

Piece	Location
referral_reward_fields_for_api()	radar/event/models.py
Organizer serializer	radar/event/serializers.py
Referee event serializers	radar/referral_app/serializers.py
Referee-event stats view	radar/referral_app/views.py
Event referral set field	radar/event/models.py (referral_referee_ids)

Run migrations after deploy: referral_commission_* columns renamed to referral_reward_*.

[Temiloluwagboyega]

any update

Referral (Referee) & Event Referral Rewards — Frontend Guide

This document covers referee authentication, referee-only event APIs, and organizer event fields for referral rewards. All paths are relative to your API base URL.

---

1. Two user types (do not mix tokens)

App	User	Auth
Referee app	SignUp (referree)	JWT from login/ or Google referee flow
Organizer app	Organizer + Django User	JWT from organizer auth

Referee JWT uses Django User.username = referee email. Use the correct token per screen.

---

2. Referee authentication

2.1 Email/password signup

1. POST /signup/ — Username, Firstname, Lastname, Phone (optional), Email, Password
2. POST /verify-otp/ — Email, otp → 201: user, referree_id

2.2 Login

POST /login/ — { "email", "password" } → access, refresh

Authorization: Bearer <access_token>

2.3 Google (referee)

POST /referee/google-signup/ — { "token": "<google_access_token>" } or access_token

2.4 Other

• POST /logout/ — { "refresh" }
• GET/PATCH /referee/profile/ — profile
• Password reset: /password/reset/, etc.
• Referee password change (authenticated): POST /password/change/
• Referee PIN:
  • POST /referee/pin/
  • POST /referee/verify-pin/
  • POST /referee/forgot-pin/
  • POST /referee/change-pin/

---

3. Referee events (use_referral: true)

Active referee JWT required (SignUp match + is_active).

Method	Path
GET	/referee/events/
GET	/referee/events/<identifier>/ (event_id or event_slug)

Reward fields (API uses 0–100 for percentage)

Field	Meaning
use_referral	Event offers referral rewards
referral_reward_type	"flat" or "percentage"
referral_reward_amount	Flat payout (currency) when type is flat
referral_reward_percentage	0–100 when type is percentage

List example

{
  "events": [{
    "event_id": "event:AB-12345",
    "event_slug": "summer-fest",
    "name": "Summer Fest",
    "event_type": "music",
    "pricing_type": "paid",
    "location": "Lagos",
    "date": "2025-06-01T18:00:00Z",
    "image": "https://...",
    "use_referral": true,
    "referral_reward_type": "percentage",
    "referral_reward_amount": null,
    "referral_reward_percentage": 7.5
  }],
  "count": 1
}

Detail adds description, max_quantity_per_booking, ticket_categories.

---

4. Organizer: referral rewards on events

POST /event/ · PATCH /events/<event_id>/update/

Field	Rules
use_referral	Boolean
referral_reward_type	If use_referral: "flat" | "percentage"
referral_reward_amount	Required for flat (positive)
referral_reward_percentage	Required for percentage: 0–100

If use_referral is false, reward fields are cleared.

GET /organizer/events/ — includes reward block above.

GET /config/ — referral_reward_types for dropdowns:

"referral_reward_types": [
  { "value": "flat", "label": "Flat amount" },
  { "value": "percentage", "label": "Percentage" }
]

---

5. Public vs referee

Endpoint	Referral reward fields
GET /events/<id>/details/	Hidden
GET /event/ (list)	Hidden
GET /referee/events/ …	Shown

---

6. Organizer referral stats endpoint

Organizer JWT required.

Method	Path	Purpose
POST	/organiser/<event_id>/referral-stats/	Bulk stats for referral IDs passed in body

Response fields

Field	Meaning
referral_name	Referee display name (Firstname + Lastname fallback to Username)
tickets_sold	Count of tickets sold by this referee for this event
referral_revenue	Sum of total_price for those sold tickets

How backend computes stats

Request body format:

{
  "referrals": [
    { "referee_id": "organiser:abc123" },
    { "referee_id": "organiser:def456" }
  ]
}

Tickets are filtered by all of these:

• Ticket.event = <event_id>
• Ticket.referral = <referee_id> (for each requested body item)
• Ticket.status in ('confirmed', 'used')

Then:

• tickets_sold = count of filtered tickets
• referral_revenue = sum of filtered total_price

---

7. Referee self stats endpoint

Referee JWT required (active referee only).

Method	Path	Purpose
GET	/referee/<event_id>/stats/	Referee sees all sold tickets for own referral id in event

Returns:

• referral_name
• referral_revenue (organizer revenue basis from tickets sold via this referee id)
• tickets_sold
• tickets (full ticket list via TicketSerializer, includes category/ticket type fields like category_name, category_price, buyer details, status, etc.)

---

8. Unique referral registration flow

When referral is used during ticket booking:

1. Referral id is saved on each ticket as Ticket.referral.
2. On confirmation (free immediately, paid via webhook/verify-payment), backend registers that id into Event.referral_referee_ids.
3. Event.referral_referee_ids behaves like a set:
   • same referee_id is stored once per event
   • repeated sales do not duplicate it

This field is internal and not exposed in normal public event payloads.

---

9. Backend reference

Piece	Location
referral_reward_fields_for_api()	radar/event/models.py
Organizer serializer	radar/event/serializers.py
Referee event serializers	radar/referral_app/serializers.py
Referee-event stats view	radar/referral_app/views.py
Event referral set field	radar/event/models.py (referral_referee_ids)

Run migrations after deploy: referral_commission_* columns renamed to referral_reward_*.

[Temiloluwagboyega]

@samkiell

[samkiell]

noted @Temiloluwagboyega

[Temiloluwagboyega]

Radar Backend — Full Project Documentation

Single reference for architecture, configuration, APIs, and flows.
API base URL is deployment-specific (e.g. https://api.example.com). Paths below are relative unless noted.

---

Table of contents

1. Overview
2. Tech stack
3. Project layout
4. Environment variables
5. Authentication
6. API reference by module
7. Ticket payment (Paystack and manual bank transfer)
8. Core domain models
9. Admin panel API
10. Caching & performance
11. Related docs

---

1. Overview

Radar is a Django REST API for an event platform:

• Students discover events, book tickets (free or paid via Paystack and/or manual bank transfer, per event), manage profile.
• Organizers create/update events, ticket categories, sell tickets, check in attendees, book on behalf of others, view wallet earnings.
• Referees (referral app) sign up separately, browse events that use referral rewards, share links.
• Admins (custom /api/admin/ API) verify events, users, payouts, system settings, hiring applications.
• Wallet holds organizer earnings from ticket sales; organizers request withdrawals.

Ticket checkout (paid events): Organizers choose allowed methods per event via payment_methods_allowed (paystack, manual_bank_transfer, or both). Students must use a method the event allows; see §7.

---

2. Tech stack

Layer	Technology
Framework	Django 6.x
API	Django REST Framework + SimpleJWT
DB	PostgreSQL (e.g. Neon) via DATABASE_URL
Cache	Redis (optional; falls back if unset)
Media	Cloudinary
Payments	Paystack; optional manual bank transfer (per-event, admin-confirmed)
Social auth	Google (django-allauth + dj-rest-auth patterns)

---

3. Project layout

backend/
├── manage.py
├── radar/
│   ├── settings.py          # Env, DB, JWT, CORS, Paystack, Cloudinary
│   ├── urls.py              # Root URL includes
│   ├── auth/                # Student & organizer registration, login, profiles
│   ├── event/               # Events CRUD, public list/detail, organizer events
│   ├── ticket/              # Booking, Paystack, manual payment forms, categories, check-in
│   ├── wallet/              # Balance, transactions, bank account, withdrawals
│   ├── bank/                # Paystack bank list + account resolve
│   ├── admin/               # Custom admin REST API (not Django admin UI only)
│   ├── analytics/           # Global / per-event analytics
│   ├── referral_app/        # Referee auth + referral program events
│   ├── hiring/              # Public job applications
│   ├── PIN/                 # User PIN set/verify/change (wallet-related UX)
│   └── common/              # Exceptions, handlers
└── docs/

Django admin UI: /admin/ (staff users).
Custom admin API: /api/admin/ (JWT after admin login).

---

4. Environment variables

Variable	Purpose
SECRET_KEY	Django secret (required)
DEBUG	true / false
ALLOWED_HOSTS	Comma-separated hosts
DATABASE_URL	PostgreSQL connection string (required)
REDIS_URL	Optional Redis for cache
PAYSTACK_SECRET_KEY	Server-side Paystack
PAYSTACK_PUBLIC_KEY	Frontend Paystack
CLOUDINARY_*	Cloud name, API key, secret
FRONTEND_URL	Used in Paystack callback URLs
CORS_ALLOWED_ORIGINS	Production CORS (required when not DEBUG)
CLIENT_ID / CLIENT_SECRET	OAuth (if used)
RENDER_EXTERNAL_HOSTNAME	Optional Render hostname

Email/SMS for OTP: check settings and auth services for provider-specific vars.

---

5. Authentication

5.1 JWT (students & organizers)

• Header: Authorization: Bearer <access_token>
• Access token lifetime: 15 minutes (see SIMPLE_JWT in settings).
• Refresh: POST /token/refresh/ with refresh token body.

5.2 Student & organizer (radar.auth)

Separate registration flows; both tie to Django User + profile models (StudentRegistration / OrganizerProfile).

5.3 Referee (radar.referral_app)

Separate signup/login; JWT is for referee users. Do not mix referee tokens with organizer tokens on the same screens.

5.4 Admin API

POST /api/admin/auth/login/ → admin JWT. Use for all /api/admin/* routes.

5.5 Public / unauthenticated

Some routes allow AllowAny (e.g. event list, Paystack webhook, hiring apply). Check each view’s permission_classes.

---

6. API reference by module

All paths are relative to API root (no trailing slash differences depend on client—Django often accepts both).

6.1 Health

Method	Path	Auth
GET	/	No
GET	/health/	No

---

6.2 Auth — students & organizers (radar.auth)

Base path: root (e.g. /login/, not /auth/login/).

Method	Path	Description
POST	/student/register/	Student signup
POST	/organizer/register/	Organizer signup
POST	/verify-otp/	OTP verification
POST	/password-reset/request/	Request reset OTP
POST	/password-reset/verify/	Verify reset OTP
POST	/password-reset/confirm/	Set new password
POST	/login/	Login (returns access + refresh)
POST	/logout/	Blacklist/refresh logout
POST	/token/refresh/	Refresh JWT
POST	/change-password/	Authenticated
POST	/student/google-signup/	Google student
POST	/organizer/google-signup/	Google organizer
GET/PATCH	/student/profile/	Student profile
GET/PATCH	/organizer/profile/	Organizer profile

---

6.3 Events (radar.event)

Method	Path	Typical auth
GET	/event/stats/	Public / varies
GET	/event/	List events (filters query params)
POST	/event/	Create event (organizer)
GET	/events/<identifier>/details/	Public detail (event_id or slug)
PATCH/PUT	/events/<event_id>/update/	Organizer owns event
GET	/config/	Public configuration payload
GET	/organizer/events/	Organizer’s events

Event status: new organizer-created events default to verified (live immediately). Admins can still set denied or pending via the dashboard. Past event dates move verified → closed. Public listing shows verified and closed events.

Paid events — payment_methods_allowed: JSON array of paystack and/or manual_bank_transfer. At least one is required when pricing_type is paid. Free events store an empty list. Exposed on public event detail and organizer event list so clients can show the correct checkout UI. GET /config/ includes ticket_payment_method_options for form labels/values.

---

6.4 Tickets (radar.ticket)

Base: /tickets/

Method	Path	Description
POST	/tickets/book/	Student books. Optional payment_method: paystack (default) or manual_bank_transfer. Paid flows must match event payment_methods_allowed.
POST	/tickets/confirm-payment/	Manual transfer confirmation (multipart); event must allow manual_bank_transfer
POST	/tickets/verify-payment/	Paystack verify with reference (auth); idempotent with webhook
POST	/tickets/paystack-webhook/	Paystack webhook (signature verified)
GET	/tickets/my-tickets/	Student’s tickets
GET	/tickets/organizer/tickets/	Organizer’s tickets across events
GET	/tickets/organizer/<event_id>/tickets/	Tickets for one event
POST	/tickets/organizer/book-for-attendee/	Paid: Paystack checkout only; 400 if event does not allow paystack
POST	/tickets/organizer/bulk-book-for-attendees/	Same Paystack rule as book-for-attendee
POST	/tickets/check-in/	Organizer check-in
GET	/tickets/categories/	List categories (query: event_id)
POST	/tickets/categories/create/	Create category
PATCH/PUT	/tickets/categories/<category_id>/	Update category

---

6.5 Wallet (radar.wallet)

Base: /wallet/

Method	Path	Description
GET	/wallet/balance/	Wallet balance
GET	/wallet/transactions/	Transaction history
GET/POST/PUT/PATCH	/wallet/bank-account/	Saved payout bank details
POST	/wallet/withdraw/	Withdrawal request
GET	/wallet/withdrawals/	Withdrawal history

---

6.6 Bank verification (radar.bank)

Base: /bank/

Method	Path	Description
GET	/bank/list/	Banks list (Paystack)
POST	/bank/verify/	Resolve account name

---

6.7 PIN (radar.PIN)

Base: root

Method	Path
GET/POST	/pin/
POST	/forgot-pin/
POST	/change-pin/
POST	/verify-pin/

---

6.8 Analytics (radar.analytics)

Base: /analytics/

Method	Path
GET	/analytics/global/
GET	/analytics/event/<event_id>/
GET	/analytics/events-summary/

Access control depends on view (organizer vs admin—confirm in code for your deployment).

---

6.9 Referral / referee (radar.referral_app)

Included after radar.auth in radar/urls.py. Paths like /signup/ and /login/ collide with auth: the first matching route wins (auth for /login/, /signup/). Referee-specific routes without collision include:

Method	Path
POST	/referee/google-signup/
GET/PATCH	/referee/profile/
GET	/referee/events/
GET	/referee/events/<identifier>/
POST	/referee/pin/
POST	/referee/verify-pin/
POST	/referee/forgot-pin/
POST	/referee/change-pin/
GET	/referee/<event_id>/stats/
POST	/organiser/<event_id>/referral-stats/

Intended referee routes in code also include: /signup/, /verify-otp/, /login/, /logout/, /password/reset/, /password/reset/verify-otp/, /set_password/, /password/change/ — same path names as auth where duplicated.

POST /organiser/<event_id>/referral-stats/ is an organizer-only bulk stats route.
It accepts a request body list:

• referrals: [{ referee_id: "<id>" }, ...]

It returns referral stats with:

• referral_name
• referral_revenue (sum of Ticket.total_price)
• tickets_sold (count of sold tickets)

Where sold tickets are Ticket.status in ('confirmed', 'used') and filtered by:

• ticket.event = <event_id>
• ticket.referral matches requested referrals[*].referee_id

GET /referee/<event_id>/stats/ is referee-only (active referee JWT).
It returns the authenticated referee's ticket-sales stats for that event using
their own referree_id, including:

• referral_name
• referral_revenue
• tickets_sold
• tickets (full ticket rows including category/ticket type fields)

Referral tracking lifecycle:

• Buyer passes referral id in booking payload (Ticket.referral).
• Free bookings are confirmed immediately. Paid Paystack bookings are confirmed by webhook or verify-payment. Paid manual bookings are confirmed when an admin approves the payment form (see §7).
• On confirmation, system registers referee id into Event.referral_referee_ids (internal set-like list).
• This collection is deduplicated per event: each referee id is added once and not duplicated by later sales.
• Event.referral_referee_ids is internal and not exposed in standard public event payloads.

See REFERRAL_REFEREE_EVENTS_FRONTEND.md for referral reward fields and organizer event API notes.

---

6.10 Hiring (radar.hiring)

Method	Path
POST	/hiring/apply/
GET	/hiring/role-types/

---

7. Ticket payment (Paystack and manual bank transfer)

7.1 Event configuration

• Field Event.payment_methods_allowed: list containing any of paystack, manual_bank_transfer (paid events only; at least one).
• POST/PATCH /event/ and PATCH /events/<id>/update/ accept payment_methods_allowed on the event serializer. Free events clear it to [].
• Booking and confirm-payment endpoints enforce the event’s list; error responses may include allowed_payment_methods.

7.2 Paystack (student or organizer-paid flows)

1. Book (student with payment_method: paystack or default, or organizer flows) creates pending tickets with shared booking_id in Paystack metadata.
2. Client opens Paystack authorization_url from initialize_payment response.
3. Success: Paystack sends charge.success webhook → tickets confirmed, wallet credited (paid events), emails sent.
4. Backup: Authenticated POST /tickets/verify-payment/ with Paystack reference idempotently confirms if webhook missed.

Wallet credits use paystack_reference on Transaction; duplicates are prevented per ticket + reference.

7.3 Manual bank transfer (student only)

1. POST /tickets/book/ with payment_method: "manual_bank_transfer" → HTTP 201, pending tickets, total_amount from TicketService.calculate_manual_bank_transfer_amount() (base + platform fixed fee, no Paystack fee).
2. Student pays out-of-band, then POST /tickets/confirm-payment/ → creates PaymentForm (radar.ticket.models.PaymentForm) with status pending (optional receipt on Cloudinary).
3. Admin GET /api/admin/payment-forms/ and PATCH /api/admin/payment-forms/<id>/status/ with confirmed or rejected. On confirmed: pending tickets for that booking_id → confirmed, wallet credited with reference manual:{payment_form_id} and per-ticket amount from calculate_manual_bank_transfer_amount, emails sent.

7.4 Referrals

Referral registration for an event is idempotent at confirmation time (unique referee IDs only), for both Paystack and admin-confirmed manual flows.

---

8. Core domain models (conceptual)

Model area	Main entities
Auth	User, StudentRegistration, OrganizerProfile
Event	Event (status, pricing, fees, payment_methods_allowed, referral reward settings, slug, internal referral_referee_ids)
Ticket	TicketCategory, Ticket (pending/confirmed/cancelled, booking_id, QR), PaymentForm (manual transfer confirmations)
Wallet	Wallet, Transaction (ticket_sale, withdrawals, fees)
Admin	SystemSettings, AuditLog, payout request models
Referral	Referee profile / SignUp, separate from student table
Hiring	HiringApplication

Exact fields: use Django models.py per app or admin serializers.

---

9. Admin panel API

Base: /api/admin/ — authenticate via POST /api/admin/auth/login/.

Area	Example paths
Auth	/auth/login/, /auth/logout/
Dashboard	/dashboard/analytics/, /dashboard/platform-revenue/, /dashboard/revenue-stats/, /dashboard/clear-cache/, /dashboard/recent-events/
Users	/users/, /users/<id>/, /users/<id>/status/, /users/<id>/delete/, /users/<organiser_id>/verify/
Events	/events/, /events/<event_id>/, /events/<event_id>/status/, /featured/, /platform-fee/, /delete/
Tickets	/tickets/, /tickets/check-in/, /tickets/cleanup/
Payouts	/payout-requests/, /payout-requests/<id>/status/
Withdrawals	/withdrawals/, /withdrawals/<transaction_id>/status/
Settings	/settings/, /audit-logs/
Manual payments	/payment-forms/, /payment-forms/<id>/status/ (confirm/reject PaymentForm)
Finance	/payment-transactions/
Notifications	/notifications/payout-requests/
Hiring	/hiring-applications/, .../<id>/, .../<id>/status/

Organizer payouts may be marked completed after manual bank transfer by staff—that is separate from ticket sales. Ticket sales can settle via Paystack or student manual transfer (admin-approved), per event settings.

---

10. Caching & performance

• Event list/detail responses may be cached (Redis); updates invalidate relevant keys.
• After ticket confirmation or booking, caches are invalidated via TicketService.invalidate_event_caches and event services.

---

11. Related docs

Document	Content
REFERRAL_REFEREE_EVENTS_FRONTEND.md	Referee auth, /referee/events/, organizer referral fields
README.md	Backend readme, ticket payment overview
CENTRALIZED_FEE_SYSTEM.md	Platform & Paystack fees; manual-transfer totals

Legacy API_COMPLETE_DOCUMENTATION.md (if present) may be partially outdated. Prefer this file + code for current behavior.

---

Quick endpoint map (copy-friendly)

GET  /
GET  /health/

POST /login/
POST /token/refresh/
GET  /event/
POST /event/
GET  /events/<id>/details/
PATCH /events/<id>/update/
GET  /organizer/events/

POST /tickets/book/
POST /tickets/confirm-payment/
POST /tickets/verify-payment/
POST /tickets/paystack-webhook/
GET  /tickets/my-tickets/
GET  /tickets/organizer/tickets/
GET  /tickets/organizer/<event_id>/tickets/
POST /tickets/organizer/book-for-attendee/
POST /tickets/organizer/bulk-book-for-attendees/
POST /tickets/check-in/
GET  /tickets/categories/
POST /tickets/categories/create/
PATCH /tickets/categories/<category_id>/

GET  /wallet/balance/
GET  /wallet/transactions/
GET|POST|PUT|PATCH /wallet/bank-account/
POST /wallet/withdraw/
GET  /wallet/withdrawals/

GET  /bank/list/
POST /bank/verify/

GET|POST /pin/
POST /forgot-pin/
POST /change-pin/
POST /verify-pin/

GET  /analytics/global/
GET  /analytics/event/<event_id>/
GET  /analytics/events-summary/

POST /signup/                    # referee
POST /login/                     # referee (same path; different app routing—use correct host/prefix if split)
GET  /referee/events/
GET  /referee/events/<id>/
POST /referee/pin/
POST /referee/verify-pin/
POST /referee/forgot-pin/
POST /referee/change-pin/
GET  /referee/<event_id>/stats/
POST /organiser/<event_id>/referral-stats/

POST /hiring/apply/
GET  /hiring/role-types/

POST /api/admin/auth/login/
... (all /api/admin/* as in section 9)

Referee vs auth URL overlap: resolve via separate subdomain, path prefix, or urls.py order per deployment.

---

Generated for the Radar backend codebase. Update this document when URLs or business rules change.