payhere-react

v1.0.0

Published

a month ago

Unofficial React SDK for PayHere payment gateway

Downloads

0High
0Medium
0Low

apexkv

payhere react reactjs payments sdk sri-lanka

📦 PayHere React SDK (Unofficial)

Unofficial React SDK for integrating the PayHere Sri Lanka payment gateway into modern React and Next.js applications.

This package provides:

A <PayHereProvider /> to load the PayHere SDK safely
A usePayHere() hook to start payments
Type-safe payment configuration
Callback isolation for multiple payment flows
Works with Vite, Next.js, TypeScript, and JavaScript

⚠️ Disclaimer

This is an unofficial SDK developed independently and is not affiliated with PayHere (Pvt) Ltd.

Use at your own risk. Always test in sandbox mode before going live.

📥 Installation

npm install payhere-react

yarn add payhere-react

🚀 Quick Start

1. Wrap your app with `PayHereProvider`

React (Vite / CRA)

import { PayHereProvider } from "payhere-react";

export function App() {
	return (
		<PayHereProvider>
			<YourApp />
		</PayHereProvider>
	);
}

Next.js (App Router)

// app/layout.tsx
import { PayHereProvider } from "payhere-react";

export default function RootLayout({ children }) {
	return (
		<html>
			<body>
				<PayHereProvider>{children}</PayHereProvider>
			</body>
		</html>
	);
}

2. Use the `usePayHere()` hook

✅ Vite / React (TypeScript)

import { usePayHere, type PayHerePaymentType } from "payhere-react";

export function PayButton() {
	const { startPayment, isLoaded } = usePayHere();

	const handlePay = () => {
		const payment: PayHerePaymentType = {
			sandbox: true,
			merchant_id: "YOUR_MERCHANT_ID",
			return_url: "https://your-site.com/return",
			cancel_url: "https://your-site.com/cancel",
			notify_url: "https://your-site.com/notify",
			order_id: "ORDER123",
			items: "Premium Plan",
			amount: "1000.00",
			currency: "LKR",
			hash: "HASH_FROM_BACKEND",
			first_name: "John",
			last_name: "Doe",
			email: "[email protected]",
			phone: "0771234567",
			address: "Colombo",
			city: "Colombo",
			country: "Sri Lanka",
		};

		startPayment(payment, {
			onCompleted: (id) => alert("Payment success: " + id),
			onDismissed: () => alert("Payment dismissed"),
			onError: (err) => alert("Payment error: " + err),
		});
	};

	if (!isLoaded) return <p>Loading PayHere...</p>;

	return <button onClick={handlePay}>Pay Now</button>;
}

✅ Vite / React (JavaScript)

import { usePayHere } from "payhere-react";

export function PayButton() {
	const { startPayment, isLoaded } = usePayHere();

	const handlePay = () => {
		startPayment({
			sandbox: true,
			merchant_id: "YOUR_MERCHANT_ID",
			return_url: "...",
			cancel_url: "...",
			notify_url: "...",
			order_id: "ORDER123",
			items: "Product",
			amount: "500.00",
			currency: "LKR",
			hash: "HASH_FROM_BACKEND",
			first_name: "John",
			last_name: "Doe",
			email: "[email protected]",
			phone: "0771234567",
			address: "Colombo",
			city: "Colombo",
			country: "Sri Lanka",
		});
	};

	if (!isLoaded) return <p>Loading...</p>;

	return <button onClick={handlePay}>Pay</button>;
}

✅ Next.js (TypeScript)

"use client";
import { usePayHere, type PayHerePaymentType } from "payhere-react";

export default function PayPage() {
	const { startPayment, isLoaded } = usePayHere();

	const pay = () => {
		const payment: PayHerePaymentType = {
			sandbox: true,
			merchant_id: "YOUR_MERCHANT_ID",
			return_url: "...",
			cancel_url: "...",
			notify_url: "...",
			order_id: "ORDER123",
			items: "Course",
			amount: "1500.00",
			currency: "LKR",
			hash: "HASH_FROM_BACKEND",
			first_name: "Jane",
			last_name: "Doe",
			email: "[email protected]",
			phone: "0712345678",
			address: "Kandy",
			city: "Kandy",
			country: "Sri Lanka",
		};

		startPayment(payment);
	};

	if (!isLoaded) return <p>Loading PayHere...</p>;

	return <button onClick={pay}>Pay Now</button>;
}

🔐 Backend Hash Generation (Required)

PayHere requires a server-generated hash.

🐍 Python Backend (payhere-python)

GitHub: 👉 https://github.com/apexkv/payhere-python

from payhere_python import generate_payment_hash

hash_value = generate_payment_hash(
    order_id="ORDER123",
    amount="1000.00",
    merchant_id="YOUR_MERCHANT_ID",
    merchant_secret="YOUR_MERCHANT_SECRET",
    currency="LKR"
)

print(hash_value)

Use this hash in your frontend payment object.

🟢 Node.js Backend (payhere-node)

GitHub: 👉 https://github.com/apexkv/payhere-node

import payhere from "payhere-node";

const hash = payhere.generatePaymentHash({
	orderId: "ORDER123",
	amount: "1000.00",
	merchantId: "YOUR_MERCHANT_ID",
	merchantSecret: "YOUR_MERCHANT_SECRET",
	currency: "LKR",
});

📚 API Reference

`usePayHere()`

Returns:

{
  startPayment: (data, config?) => void;
  isLoaded: boolean;
  error: string | null;
  isError: boolean;
}

Optional Callbacks

startPayment(payment, {
	onCompleted: (orderId) => {},
	onDismissed: () => {},
	onError: (error) => {},
});

All callbacks are optional.

🔒 Security Notes

Never expose merchant_secret in frontend
Always generate hash in backend
Use sandbox before production
Validate PayHere webhooks

📄 License

This project is licensed under the GNU General Public License v3.0 Same license as the Python SDK.

👨‍💻 Author

Kavindu Harshitha (apexkv)
GitHub: apexkv
Website: apexkv.com
Email: [email protected]

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

⭐ Support the Project

If this helps you:

Star the repo
Share with other devs
Contribute improvements

©️ Copyright

Copyright (c) 2026 Kavindu Harshitha(apexkv). Licensed under the GNU GPL v3.