Payments, Ticketing & Refunds

Overview

Nigall uses Stripe for ticket checkout, attendee registration payments, subscription billing, and module payments (exhibitors, vendors, sponsors). Platform fees split revenue between Nigall and organizers based on subscription tier.

Purpose

Collect payments securely with transparent fee structure and webhook-confirmed fulfillment.

Who should use it

  • Organizers selling tickets
  • Finance reviewing payouts
  • Attendees completing checkout
  • Admins configuring Stripe

Benefits

  • Stripe Checkout sessions
  • Platform fee: 5% (Free/Essentials) or 3% (Presenter Pro/Operations Suite)
  • Payment history for users
  • Webhook idempotency for fulfillment
Action Path
Legacy ticket checkout /payments/checkout/<event_id>/<tag>/
Ticket review /payments/tickets/<event_id>/<tag>/review/
Ticket payment /payments/tickets/<event_id>/<tag>/pay/
Attendee registration pay /attendees/registrations/<pk>/pay/
Payment success /payments/success/
My payments /payments/my-payments/
Subscription checkout /payments/subscription/checkout/
Stripe webhook /payments/webhook/
Event orders (host) /attendees/events/<pk>/<tag>/orders/

Prerequisites

  • Stripe API keys in environment
  • Webhook endpoint registered pointing to /payments/webhook/
  • Paid event or tier configured
  • Organizer account for fee tier lookup

Step-by-step — Attendee pays for registration

  1. Complete registration form.
  2. Redirect to /attendees/registrations/<pk>/payment/.
  3. Click pay → Stripe Checkout (registration_pay_stripe).
  4. Return to success URL → ticket issued.
  5. Webhook confirms Payment record with fee split.

Step-by-step — Organizer views revenue

  1. Open event orders: /attendees/events/<pk>/<tag>/orders/.
  2. Review payment status, platform fee, organizer payout.
  3. Cross-check /payments/my-payments/ for buyer history.

Field descriptions

Concept Description
calculate_payment_split() Computes platform_fee, organizer_payout
PLATFORM_FEE_RATES 5% free/basic, 3% plus/pro
Payment.platform_fee Stored on confirmation
organizer_subscription_plan Plan at time of payment
Sponsor fees Separate sponsor_platform_fee_percent on event

Subscription prices (USD)

Plan Monthly Annual
Free $0 $0
Essentials $29 $276
Presenter Pro $79 $756
Operations Suite $149 $1,428

Business rules

Rule Detail
Fee tier Based on organizer subscription_plan at payment time
Rounding Fees rounded half-up to cent
Subscriptions Balance due calculated on plan changes
Refunds Process in Stripe Dashboard; update Nigall records manually/admin
Free events Skip Stripe; is_free=True

Validation rules

  • Positive payment amounts
  • Valid Stripe session before ticket confirm

User permissions

Role Pay View orders Webhook
Buyer ✅ Own ❌
Host ❌ ✅ event ❌
System ❌ ❌ ✅ Stripe

Workflow

sequenceDiagram participant User participant Nigall participant Stripe User->>Nigall: Initiate pay Nigall->>Stripe: Create Checkout Session Stripe->>User: Payment UI User->>Stripe: Complete Stripe->>Nigall: Webhook Nigall->>Nigall: calculate_payment_split + fulfill ticket

Examples

$100 ticket, Essentials organizer: $5 platform fee, $95 organizer payout.

$100 ticket, Pro organizer: $3 platform fee, $97 payout.

Best practices

  • Test with Stripe test keys first
  • Monitor webhook failures in logs
  • Document refund policy in attendee_registration_info

Tips

  • Subscription upgrade: /pricing/select/ → /payments/subscription/checkout/
  • Module payments use app-specific success URLs

Common mistakes

Mistake Result Fix
Webhook not configured Paid but no ticket Register webhook URL
Wrong Stripe mode Live/test mismatch Align keys

FAQs

Where to refund?
Stripe Dashboard primary; sync registration status in Nigall.

Are Stripe fees included?
Platform fee is Nigall's; Stripe processing separate per Stripe pricing.

Troubleshooting

Symptom Cause Fix
Payment success, no ticket Webhook failed Replay webhook
Wrong fee % Plan changed mid-day Fee locked at payment record

Screenshot placeholders

  • [SCREENSHOT: Stripe checkout]
  • [SCREENSHOT: Orders table with fee columns]
  • [SCREENSHOT: My payments history]

Administrator notes

  • payments/services.py — fee rates and subscription prices
  • payments/views.py — webhook handler
  • Never commit Stripe secrets

Developer/API notes

Function Location
calculate_payment_split payments/services.py
Webhook POST /payments/webhook/
Metadata session includes platform_fee, organizer_payout

See also: Billing & Subscriptions

Help home Back to Nigall