onepay-sdk/README.md

A simple payment gateway for Node.js

# 🧾 OnePay-SDK - Unified Payment Gateway Wrapper

OnePay-SDK is a lightweight and developer-friendly TypeScript package that simplifies integration with multiple payment gateways such as **Stripe** and **Razorpay** in a single unified interface.

> 🔐 Use OnePay-SDK to easily validate and manage API keys for multiple gateways in one project.

---

## 🚀 Features

- ✅ Multi-gateway support (Stripe & Razorpay)
- 🛠️ Validate API keys with easy-to-use methods
- 💳 Create, verify, and process payments through a consistent API
- 🔄 Process refunds with a unified interface
- 🔍 Retrieve payment details across gateways
- 🔌 Plug-and-play class-based API
- 💡 Written in TypeScript (with full types support)
- 🔧 Easily extendable for more gateways in future

---

## 📦 Installation

```bash
npm install onepay-sdk
# or
yarn add onepay-sdk
```

---

## 🛠️ Usage

### Initialize OnePay-SDK

To start using OnePay-SDK, initialize it with the API keys for the supported gateways:

```typescript
import { OnePay } from "onepay-sdk";

const onePay = new OnePay([
  { gateway: "stripe", apiKey: "your-stripe-api-key" },
  { gateway: "razorpay", apiKey: "your-razorpay-key-id", apiSecret: "your-razorpay-key-secret" },
]);
```

### Validate Gateways

You can validate the configured gateways to ensure the API keys are correct:

```typescript
const stripeValidation = await onePay.validateGateway("stripe");
console.log(stripeValidation);

const razorpayValidation = await onePay.validateGateway("razorpay");
console.log(razorpayValidation);
```

### Create Payments

OnePay allows you to create payments for the supported gateways:

#### Razorpay

```typescript
const razorpayPayment = await onePay.createPayment({
  gateway: "razorpay",
  amount: 50, // Amount in regular currency (will be converted to paise internally)
  currency: "INR",
  description: "Premium Subscription",
  metadata: { customer_id: "cust_123", product_id: "prod_456" }
});
console.log(razorpayPayment);
// Returns Razorpay order details including orderId
```

#### Stripe

```typescript
const stripePayment = await onePay.createPayment({
  gateway: "stripe",
  amount: 50, // Amount in regular currency (will be converted to cents internally)
  currency: "usd",
  description: "Test Payment",
  customerEmail: "customer@example.com",
  paymentMethodTypes: ["card"],
  customerId: "cust_123456", // Optional Stripe customer ID
  metadata: { order_id: "6735" }
});
console.log(stripePayment);
// Returns a client secret that can be used with Stripe.js
```

### Verify Payments

After payment completion on the client side, you can verify payments:

#### Razorpay Verification

```typescript
const verifyRazorpay = await onePay.verifyPayment({
  gateway: "razorpay",
  paymentId: "pay_123456789",
  orderId: "order_123456789",
  signature: "signature_from_razorpay_callback" 
});
console.log(verifyRazorpay);
```

#### Stripe Verification

```typescript
const verifyStripe = await onePay.verifyPayment({
  gateway: "stripe",
  paymentId: "pi_123456789" // Payment Intent ID
});
console.log(verifyStripe);
```

### Process Refunds

You can process refunds for completed payments:

```typescript
// Full refund
const fullRefund = await onePay.refundPayment(
  "stripe", 
  "pi_123456789"
);

// Partial refund
const partialRefund = await onePay.refundPayment(
  "razorpay", 
  "pay_123456789", 
  25.00 // Refund amount in regular currency
);
```

### Retrieve Payment Details

Get payment information at any time:

```typescript
const paymentDetails = await onePay.getPaymentDetails(
  "stripe", 
  "pi_123456789"
);
console.log(paymentDetails);
```

---

## 🧩 Type Definitions

OnePay-SDK exports TypeScript interfaces to help with development:

```typescript
// Initialize payment gateways
type KeyProps = {
  gateway: 'stripe' | 'razorpay'; 
  apiKey: string;
  apiSecret?: string;
}

// Create payment payload
type PaymentPayload = {
  gateway: 'stripe' | 'razorpay';
  amount: number;
  currency: string;
  description: string;
  customerEmail?: string;
  metadata?: Record<string, any>;
  paymentMethodTypes?: string[];
  customerId?: string;
  receiptId?: string;
}

// Verify payment payload
type PaymentVerificationPayload = {
  gateway: 'stripe' | 'razorpay';
  paymentId: string;
  orderId?: string; // For Razorpay
  signature?: string; // For Razorpay
}
```

## 📋 Response Format

All methods return a consistent response format:

```typescript
{
  success: boolean;
  gateway: 'stripe' | 'razorpay';
  message?: string; // Error message if success is false
  
  // For Stripe
  clientSecret?: string;
  paymentIntentId?: string;
  
  // For Razorpay
  order?: any;
  orderId?: string;
}
```

---

## 🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

## 📄 License

[MIT](LICENSE)