Skip to main content

Payments and Orders

The platform supports multiple checkout paths and routes payment behavior through both Next.js and Convex-backed configuration.

Active providers in the codebase​

  • Paystack
  • Flutterwave
  • Stripe
  • free-ticket path
  • crypto placeholder flow

Checkout entry point​

The main Next.js checkout route is app/api/payments/checkout/route.ts.

Its current routing behavior is:

  • explicit Paystack selection goes to Paystack
  • explicit Flutterwave selection goes to Flutterwave
  • explicit Stripe selection goes to Stripe
  • otherwise NGN defaults to Paystack
  • non-NGN defaults to Stripe

Provider notes​

Paystack​

  • Strong default for NGN
  • Expects minor units
  • Returns a hosted authorization URL
  • Falls back to a mock success URL when the secret key is missing

Stripe​

  • Used for non-NGN or explicit Stripe checkouts
  • Creates hosted checkout sessions directly from the API route
  • Falls back to a mock success URL when the secret key is missing

Flutterwave​

  • Available as an alternate hosted checkout path
  • Uses major units when creating the payment session

Provider configuration sources​

Checkout reads from Convex payment settings first and then falls back to process environment values. This allows admin-managed provider metadata and per-provider credentials without hardcoding everything in the frontend.

Order lifecycle​

At a high level:

  1. Attendee selects ticket(s)
  2. Checkout route initializes provider session
  3. Provider redirect completes
  4. Webhook or success handler reconciles order state
  5. Passes, emails, and post-purchase assets are generated
  • app/api/payments/checkout/route.ts
  • app/e/[slugOrId]/checkout/CheckoutContent.tsx
  • convex/orders.ts
  • convex/passes.ts
  • convex/actions.ts
  • convex/settings.ts

Operational cautions​

  • Amounts are stored in minor units in the web app layer.
  • Provider expectations are not identical; Paystack and Stripe differ from Flutterwave on amount formatting.
  • Missing provider secrets may intentionally degrade to mock success paths in development.