[Enhancement] Course enrollment route has a mock payment flow — real payment processor not integrated

[RUKAYAT-CODER]

Overview

src/app/api/courses/[id]/enroll/route.ts contains a TODO to replace the mock payment flow with a real payment processor and database write. Users can enroll in paid courses without actually being charged, and enrollment records are not persisted — meaning access is lost on restart.

Specifications

Features:

• Paid course enrollment requires a successful payment via Stripe
• Enrollment records are persisted to the database
• Failed payments return HTTP 402 with a clear error

Tasks:

• Integrate Stripe Checkout: create a checkout session and return the session URL to the client
• Handle the Stripe webhook checkout.session.completed to write the enrollment record
• Create an enrollments table: (user_id, course_id, enrolled_at, payment_id, status)
• Gate lesson access on the enrollment record

Impacted Files:

• src/app/api/courses/[id]/enroll/route.ts
• src/app/api/webhooks/stripe/route.ts (new)
• src/lib/db/ (new migration)

Acceptance Criteria

• Enrolling in a paid course redirects to Stripe Checkout
• Successful payment creates an enrollment record in the database
• Enrollment survives a server restart and gates lesson access correctly

[xiaohou2503687-design]

For the paid-course enrollment flow, the important part is to avoid trusting the client or the success URL as proof of payment.

A minimal safe flow would be:

1. Create the Stripe Checkout Session server-side with courseId and userId in metadata.
2. Return only the Checkout URL to the client.
3. In checkout.session.completed, verify the webhook signature, read metadata, and create the enrollment row in the DB.
4. Make the enroll API return 402 or a checkout URL until the entitlement row exists.
5. Add an idempotency guard so webhook retries do not create duplicate enrollments.

I offer a fixed $79 PaySchema review for checkout + webhook + entitlement logic if you want a second pass before shipping: https://xiaohou2503687-design.github.io/shipfast-oss/payschema.html

[Opulencechuks]

@Opulencechuks has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I am confident that I can implement this having worked on similar issues in the past

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Opulencechuks to this issue.