[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

[deslawson]

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

Id love to work on this issue

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

[nanaabdul1172]

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

Hello,

I'd like to take on this issue. I can implement the required changes, ensuring they are secure, efficient, and easy to maintain.
I'll include relevant tests, handle edge cases, update documentation as needed, and verify that the changes integrate cleanly with the existing system without introducing regressions.

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

[iwayemi5]

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

I would like to work on this issue as I have reviewed the scope, I should have a PR Ready in 50 minutes.

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

[drips-wave]

Congratulations, @iwayemi5! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @iwayemi5: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊