tss_razorpay_plugin 1.0.2

A comprehensive Flutter plugin for Razorpay payment integration with full support for mobile (iOS/Android) and web platforms, featuring modern dart:js_interop.

tss_razorpay_plugin

A comprehensive Flutter package for seamless Razorpay payment integration with full support for mobile (iOS/Android) and web platforms.

Features

✅ Cross-Platform Support - Works on Android, iOS, and Web
✅ Modern Web Integration - Uses latest dart:js_interop for web platform
✅ Type-Safe - Full null safety support
✅ Production-Ready - Battle-tested code with comprehensive error handling
✅ Easy Integration - Simple API with detailed documentation
✅ Customizable - Flexible callbacks and payment status tracking

Installation

Add to your pubspec.yaml:

dependencies:
  tss_razorpay_plugin: ^1.0.1

Run:

flutter pub get

Web Setup (Required for Web Platform)

1. Add Scripts to index.html

Add these scripts to your web/index.html before the closing </head> tag:

<!-- Razorpay Checkout SDK -->
<script src="https://checkout.razorpay.com/v1/checkout.js"></script>
<script src="tssrz.js"></script>

2. Copy tssrz.js

Copy the tssrz.js file from the package to your project:

cp tss_razorpay_plugin/web/tssrz.js your_project/web/

Mobile (iOS/Android): No additional setup needed!

Usage

Get Payment Details from Your Server

First, create a payment on your server and get the response:

// Example API call to your backend
final response = await http.post('/api/payment/create', body: {
  'amount': '1000.00',
  'orderId': 'ORD123',
});

final paymentData = json.decode(response.body);
// paymentData contains: gwk, gwAmt, pgwRequestId, buyerPhNo, buyerEmail

Use RzPage with Server Response

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => RzPage(
      razorpayKey: paymentData['gwk'],              // Razorpay key from server
      amt: paymentData['gwAmt'],                     // Amount in paise from server
      companyName: 'Your Company',
      orderDescription: 'Order #12345',
      orderId: paymentData['pgwRequestId'],          // Razorpay order ID from server
      buyerPhNo: paymentData['buyerPhNo'],           // Buyer phone from server
      buyerEmail: paymentData['buyerEmail'],         // Buyer email from server
      callbacks: RzCallbacks(
        onPaymentSuccess: () {
          Navigator.pop(context);
          // Update payment status on your server
        },
        onPaymentError: () {
          Navigator.pop(context);
          // Handle error
        },
      ),
    ),
  ),
);

Advanced Example with Payment Tracking

RzPage(
  amt: '100000',
  companyName: 'My Store',
  orderDescription: 'Premium Subscription',
  razorpayKey: 'rzp_live_xxxxxxxxxx',
  orderId: 'order_xxxxxxxxxxxxx',
  buyerPhNo: '9876543210',
  buyerEmail: '[e-mail]',
  callbacks: RzCallbacks(
    onPaymentSuccess: () {
      // Handle success - verify payment on backend
      _verifyPaymentOnServer();
      Navigator.pop(context);
    },
    onPaymentError: () {
      // Handle failure
      _logPaymentFailure();
      Navigator.pop(context);
    },
  ),
  // Optional: Track payment updates
  onPaymentUpdate: (status, data) {
    print('Payment Status: $status');
    print('Payment Data: $data');
    
    if (status == 'SUCCESS') {
      final paymentId = data['razorpay_payment_id'];
      final orderId = data['razorpay_order_id'];
      final signature = data['razorpay_signature'];
      // Send to your backend for verification
    }
  },
)

API Reference

RzPage Widget

Main widget for initiating Razorpay payment.

Parameters

Parameter	Type	Required	Description
amt	String	✅	Payment amount in paise (e.g., "100000" for ₹1000.00)
companyName	String	✅	Your company/app name shown in payment UI
orderDescription	String	✅	Description of the order/payment
razorpayKey	String	✅	Your Razorpay API key (test or live)
orderId	String	✅	Order ID from Razorpay Order API
buyerPhNo	String	✅	Customer's phone number
buyerEmail	String	✅	Customer's email address
callbacks	RzCallbacks	✅	Success and error callback handlers
onPaymentUpdate	Function?	❌	Optional callback for payment status updates

RzCallbacks

Callback handlers for payment events.

RzCallbacks(
  onPaymentSuccess: () {
    // Called when payment succeeds
  },
  onPaymentError: () {
    // Called when payment fails or is cancelled
  },
)

Important Notes

Amount Format

Always provide the amount in paise (smallest currency unit):

• ₹10.00 = "1000"
• ₹100.00 = "10000"
• ₹1,000.00 = "100000"

Order Creation

You must create a Razorpay order on your backend before calling RzPage:

// Backend example (Node.js)
const order = await razorpay.orders.create({
  amount: 100000,  // amount in paise
  currency: "INR",
  receipt: "order_rcptid_11"
});
// Use order.id in your Flutter app

Payment Verification

Always verify the payment signature on your backend after receiving success callback. Never trust frontend confirmations alone.

// Backend verification example
const crypto = require('crypto');

function verifySignature(orderId, paymentId, signature, secret) {
  const text = orderId + "|" + paymentId;
  const generated_signature = crypto
    .createHmac('sha256', secret)
    .update(text)
    .digest('hex');
  return generated_signature === signature;
}

API Keys

• Use test keys (rzp_test_xxx) during development
• Use live keys (rzp_live_xxx) in production
• Never commit API keys to version control

Platform-Specific Behavior

Android & iOS

• Uses native Razorpay SDK via razorpay_flutter plugin
• Launches native payment UI
• Supports UPI, cards, wallets, and net banking

Web

• Uses Razorpay Checkout.js library
• Custom JavaScript integration via dart:js_interop
• Requires tssrz.js file in web/ directory
• Supports all payment methods available on web

Troubleshooting

Web: "openRazorpayTSS function not found"

Solution:

1. Ensure tssrz.js is copied to your web/ directory
2. Verify both scripts are loaded in index.html:

   <script src="https://checkout.razorpay.com/v1/checkout.js"></script>
   <script src="tssrz.js"></script>
   

3. Check browser console for script loading errors

Mobile: Payment modal not opening

Solution:

1. Verify Razorpay API key is correct
2. Ensure order ID is valid and created via Razorpay API
3. Check app permissions (if needed)
4. Enable debug mode to see detailed errors

Payment succeeds but callback not triggered

Solution:

1. Ensure callbacks are properly defined
2. Check for navigation issues (context might be disposed)
3. Verify JavaScript integration for web platform

Example Project

See the example/ directory for a complete working application demonstrating:

• Payment initiation
• Success/error handling
• Navigation flow
• Best practices

License

MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Issues: GitHub Issues
• Razorpay Documentation: https://razorpay.com/docs/

Credits

Built with ❤️ for the Flutter community.

Razorpay is a trademark of Razorpay Software Private Limited.