Razorpay Payment Gateway Integration Template

[AchuAshwath]

Summary

This PR adds Razorpay payment gateway integration to the Full Stack FastAPI Template, enabling one-time payments with complete frontend checkout UI, payment verification, and webhook handling.

What's Added

Backend

• Payment API Endpoints (/api/v1/payments/*):

  • POST /create-order - Create Razorpay orders and save to database
  • POST /verify - Verify payment signatures
  • POST /webhook - Handle Razorpay webhook events
  • GET /orders - List user orders (paginated)
  • GET /orders/{order_id} - Get order details

• Database Models:

  • Order model - Stores payment orders with Razorpay order IDs
  • Payment model - Stores payment records linked to orders
  • Automatic Alembic migration included

• Services:

  • RazorpayService - Encapsulates Razorpay API interactions
  • Secure signature verification for payments and webhooks
  • Payment capture handling

• Configuration:

  • Environment variables: RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET, RAZORPAY_WEBHOOK_SECRET
  • Optional integration (gracefully handles missing keys)

Frontend

• Payment Components:

  • Checkout page (/checkout) with integrated payment form and analytics dashboard
  • Payment success/failure pages
  • Payment analytics with statistics and recent orders table

• Integration:

  • Razorpay Checkout.js integration via CDN
  • TypeScript type definitions for Razorpay
  • Auto-generated OpenAPI client integration

Key Features

✅ Complete Payment Flow: Order creation → Razorpay checkout → Signature verification → Database updates
✅ Secure: Payment signature verification using Razorpay's secure hash
✅ Webhook Support: Real-time payment status updates via webhooks
✅ Analytics: Built-in payment dashboard showing totals, success rates, and history
✅ Type-Safe: Full TypeScript support with auto-generated API client
✅ Optional: Gracefully handles missing Razorpay configuration (returns 503)

Breaking Changes

None - This is a purely additive feature. Existing functionality remains unchanged.

Testing

Prerequisites

1. Create a Razorpay account (free test mode available)
2. Get test API keys from Razorpay Dashboard
3. Add to .env:

   RAZORPAY_KEY_ID=rzp_test_xxxxxxxxxxxxx
   RAZORPAY_KEY_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxx

Test Steps

1. Start the stack: docker compose watch
2. Navigate to /checkout page
3. Enter payment amount
4. Use Razorpay test card: 4111 1111 1111 1111
5. Complete payment flow
6. Verify order appears in payment dashboard

Test Cards

• Success: 4111 1111 1111 1111
• Failure: 4000 0000 0000 0002
• See Razorpay Test Cards

Files Changed

Backend

• backend/app/models.py - Added Order and Payment models
• backend/app/crud.py - Added payment CRUD operations
• backend/app/api/routes/payments.py - New payment endpoints
• backend/app/services/razorpay_service.py - Razorpay service wrapper
• backend/app/core/config.py - Added Razorpay configuration
• backend/app/api/main.py - Registered payments router
• backend/pyproject.toml - Added razorpay dependency
• backend/app/alembic/versions/7c4cf1d2308a_add_payment_models.py - Database migration

Frontend

• frontend/src/components/Payments/Checkout.tsx - Checkout page component
• frontend/src/components/Payments/PaymentSuccess.tsx - Success page
• frontend/src/components/Payments/PaymentFailure.tsx - Failure page
• frontend/src/components/Payments/PaymentAnalytics.tsx - Analytics component
• frontend/src/routes/_layout/checkout.tsx - Checkout route
• frontend/src/routes/payment-success.tsx - Success route
• frontend/src/routes/payment-failure.tsx - Failure route
• frontend/src/components/Common/SidebarItems.tsx - Added checkout navigation
• frontend/index.html - Added Razorpay Checkout.js script
• frontend/src/vite-env.d.ts - Added Razorpay type definitions

Documentation

• README.md - Added payment integration section
• backend/README.md - Added payment API documentation and migration guide

Documentation

• Setup instructions: See README.md Payment Integration section
• API details: See backend/README.md#payment-api-endpoints
• Migration guide: See backend/README.md#database-migrations-with-alembic
• Webhook setup: See backend/README.md#webhook-setup-for-local-development

Dependencies Added

• razorpay>=1.4.2 (Python package)

Checklist

• Code follows project style guidelines
• Tests pass (no existing tests broken)
• Documentation updated
• Migration included and tested
• No breaking changes
• Optional integration (graceful handling when not configured)
• Security: Signature verification implemented
• Frontend client auto-generated from OpenAPI schema

Notes

• Razorpay integration is optional - the template works without it
• Test mode keys work immediately (no KYC required)
• Production requires KYC and live keys
• Webhook secret is optional (only needed for production webhooks)

---

This enables teams to quickly add payment capabilities to their FastAPI applications without building the integration from scratch.

[stevleibelt]

@AchuAshwath, thanks for your work. Why should this razorpayment, as a special service code, be part of a general fastapi template like this repository is good for?

From my point of view, it makes more sense that you maintain a up to date branch with this feature under your name.

Cheers,
Stev

[AchuAshwath]

Now that i think about it more, your point makes more sense @stevleibelt .

I was thinking, any web application thats being developed has a goal of being monetised, so I thought for a massive starter template like this repo would benefit from having a ready to configure payment integration, because I would like a repo to be like this.

My goal was to implement many payment services, not just razorpayment but to include many more widely used payment gateways - it would make the general template more complex and add unwanted scope to the project.

if the scope is ready to be be explored, How should I make this a more compelling addition to the project?

Thanks for being nice even though I gave slop of a PR 🤣 , I am just starting out with Open source contribution. If you would like to nudge me on better path I would really appreciate it.

Cheers,
Ashwath

[stevleibelt]

@AchuAshwath being nice pays of in the long run. Thank you to for noticing the choice of my words.

Since I am not a project maintainer, I am not in the power to guide you the right way.

Maybe, this project has reached a size that it make sense to create a "list of cool projects/additional implementations" file. This created file contains of links to other branches like yours to show how easy it is to implement things like your payment service.
This way, we could solve the following problems:

• Keeping the main template small and maintainable
• Moving the maintenance afford to people who have implemented the additional service
• Show the user, that they are leaving the project maintainers code
• Link together the amazing work done by all the open-source's outside

Again, thanks for your work and welcome to the world of open source :-).

Have a great day,
Stev

[AchuAshwath]

I'll keep my repo up to date with the payment implementation, thank you for being such a chad.
Excited to be featured 😆

it was nice knowing you @stevleibelt and also I used to use arch btw 🥂