unipayconnect

UnipayConnect 👋

UnipayConnect is a unified payment library designed to make handling payments with Stripe, PayPal, and Razorpay simple and efficient. It abstracts away the complexities of using multiple payment APIs and offers a straightforward interface for initializing payments, capturing payments, and verifying webhook events.

Key Features

• Multi-provider support: Integrates Stripe, PayPal, and Razorpay into one unified API.
• Easy-to-use API: Functions for creating checkout sessions, capturing payments, and verifying webhooks.
• Customizable Checkout: Build Stripe-like checkout pages with flexibility.
• Simple integration: Focus on your app while UnipayConnect handles payments.

Requirements

Before getting started, ensure you have the following:

• Node.js >= 12.x
• React (for frontend use)
• Express (backend server framework)
• API keys for Stripe, PayPal, and Razorpay

Installation

You can install the UnipayConnect package using npm:

npm install unipayconnect

Environment Setup

.env

Create a .env file and add your API keys and connection details:

STRIPE_SECRET_KEY=<your-stripe-secret-key>
STRIPE_WEBHOOK_SECRET=<your-stripe-webhook-secret>
PAYPAL_CLIENT_ID=<your-paypal-client-id>
PAYPAL_CLIENT_SECRET=<your-paypal-secret>
PAYPAL_WEBHOOK_ID=<your-paypal-webhook-id>
NODE_ENV='sandbox'||'production' for paypal
RAZORPAY_KEY_ID=<your-razorpay-key-id>
RAZORPAY_KEY_SECRET=<your-razorpay-secret>
RAZORPAY_WEBHOOK_SECRET=<your-razorpay-webhook-secret>
PORT=<your-port>
JWT_SECRET='<your-jwt-secret>'
REACT_APP_API_URL=http://localhost
REACT_APP_RAZORPAY_KEY_ID=<your-razorpay-key-id>
REACT_APP_RAZORPAY_KEY_SECRET=<your-razorpay-key-secret>
REACT_APP_STRIPE_SECRET_KEY=<your-stripe-webhook-secret>
REACT_APP_PAYPAL_CLIENT_ID=<your-paypal-client-id>
REACT_APP_PAYPAL_CLIENT_SECRET=<your-paypal-secret>
REACT_APP_RAZORPAY_URL='https://checkout.razorpay.com/v1/checkout.js'

How to Use UnipayConnect

• Initialize UnipayConnect In your backend application, initialize the library like this:

const unipayconnect = require("unipayconnect");
// Import the payment providers
const StripeProvider = require("@unipayconnect/core/gateways/stripe");
const PayPalProvider = require("@unipayconnect/core/gateways/paypal");
const RazorPayProvider = require("@unipayconnect/core/gateways/razorpay");

• Regitser Register the providers with your credentials like this:

// Register the providers with your credentials
const stripe = unipayconnect.register(
  "stripe",
  new StripeProvider(process.env.REACT_APP_STRIPE_SECRET_KEY)
);
const paypal = unipayconnect.register(
  "paypal",
  new PayPalProvider(process.env.REACT_APP_PAYPAL_CLIENT_SECRET)
);
const razorpay = unipayconnect.register(
  "razorpay",
  new RazorPayProvider({
    key_id: process.env.REACT_APP_RAZORPAY_KEY_ID,
    key_secret: process.env.REACT_APP_RAZORPAY_KEY_SECRET,
  })
);

• Create Checkout Session You can create a checkout session for Stripe, PayPal, or Razorpay. This example shows how to use it:

const session = await unipayconnect.createCheckoutSession({
  price: 250, //total value of the cart
  currency: "USD",
  providers: ["razorpay", "stripe", "paypal"],
  //Not Mandatory
  name: "Avanish",
  email: "[e-mail]",
  products: [
    {
      name: "Nike Tshirt",
      price: 50,
      quantity: 1,
    },
    {
      name: "Puma shoes",
      price: 100,
      quantity: 2,
    },
  ],
});

• providers: Name of the provider you want to use (stripe, paypal, or razorpay).
• price: Total price of the checkout session.
• currency: Currency code (e.g., 'USD', 'INR').
• products: Array of product objects containing name, quantity, and price.

-Capture Payment After a successful checkout, capture the payment:

const paymentResult = await unipayconnect.capturePayment({
  providerName: "razorpay", // Choose provider
  paymentId: "pay_ABC123", // Payment ID from the provider
  amount: 100, // Only required for Razorpay
});

• providerName: Payment provider (required).

• paymentId: The ID of the payment (from Stripe/PayPal/Razorpay).

• amount: Total payment amount (required for Razorpay).

• Verify Webhook Events Webhooks are crucial for receiving updates from payment providers. Here's how you verify the webhook data:

const isValid = unipayconnect.verifyWebhookPayload(
  req.body, // Webhook payload received from the provider
  req.headers["provider-name"] // Provider name ('stripe', 'paypal', 'razorpay')
  // Signature from webhook headers
  req.headers['paypal-transmission-sig']
  || req.headers['stripe-signature']
  || req.headers['X-Razorpay-Signature']
);

• Available Methods Each provider has its own methods for interacting with their API. Here's a quick overview of the common methods available:

  token: Here, refers to token recieved after creating checkout session.

  • Stripe: initPayment(token),getProvider(providerName), getAllProviders(), register(providerName,providerInstance), etc.

  • PayPal: initPayment(token),getProvider(providerName), getAllProviders(), register(providerName,providerInstance), etc.

  • Razorpay: initPayment(token),getProvider(providerName), getAllProviders(), register(providerName,providerInstance), etc.

• Additional Configuration You can configure additional options such as successUrl, cancelUrl, and more depending on the gateway you're using. I motivate you to play with each provider for more detailed options.

API Routes Examples

• Create Checkout Session (Example API Route)

app.post("/api/v1/payments/create-checkout-session", async (req, res) => {
  const { price, currency, providers, products } = req.body;
  const sessionData = await unipayconnect.createCheckoutSession({
    providerName: providers[0],
    price,
    currency,
    products,
  });
  res.status(200).json(sessionData);
});

• Capture Payment (Example API Route)

app.post("/api/v1/payments/capture", async (req, res) => {
  const { providerName, paymentId, amount } = req.body;
  const result = await unipayconnect.capturePayment({
    providerName,
    paymentId,
    amount,
  });
  res.status(200).json(result);
});

• Verify Webhook (Example API Route)

app.post("/api/v1/payments//verify-webhook", (req, res) => {
  const providerName = req.headers["provider-name"];
  const signature =
    req.headers["stripe-signature"] ||
    req.headers["paypal-transmission-sig"] ||
    req.headers["X-Razorpay-Signature"];
  const verified = unipayconnect.verifyWebhookPayload(
    providerName,
    req.body,
    signature
  );
  res.status(verified ? 200 : 400).json({ verified });
});

• Webhook Setup Guide

1. Generate a Webhook URL for Local Development: For local development, you need a publicly accessible URL to receive webhook events. You can use ngrok or localtunnel for this.

• Using ngrok (Recommended)

  1. Install ngrok (if not already installed):

  npm install -g ngrok
  

  1. Start ngrok on your local server port (e.g., 8080):

  ngrok http 8080
  

  1. Copy the Forwarding URL provided by ngrok (e.g., https://your-ngrok-subdomain.ngrok-free.app).

  2. Once you have the publicly accessible URL, add it to your payment provider's webhook settings.

  You're all set! Your local environment is now ready to receive webhooks.

Client Setup

To install and set up the unipayconnect/packages/client on your local machine, follow these steps:

Prerequisites

1. Node.js: Ensure you have Node.js installed on your machine. You can download it from nodejs.org.

2. npm: npm is included with Node.js. You can check if it's installed by running the following command in your terminal:

   npm -v
   

Step-by-Step Installation

1. Clone the Repository:

First, clone the unipayconnect repository from GitHub:

git clone https://github.com/yourusername/unipayconnect.git

1. Navigate to the Client Directory:

Change your working directory to the client package:

cd unipayconnect/packages/client

1. Install Dependencies:

Install the required dependencies using npm:

npm install

1. Set Up Environment Variables:

Create a .env file in the packages/client directory to store your API keys and any other environment variables required for your application:

touch .env

Add your configuration details:

REACT_APP_API_URL=http://localhost
REACT_APP_RAZORPAY_KEY_ID=<your-razorpay-key-id>
REACT_APP_RAZORPAY_URL='https://checkout.razorpay.com/v1/checkout.js'
REACT_APP_RAZORPAY_KEY_SECRET=<your-razorpay-key-secret>
REACT_APP_STRIPE_SECRET_KEY=<your-stripe-webhook-secret>
REACT_APP_PAYPAL_CLIENT_ID=<your-paypal-client-id>
REACT_APP_PAYPAL_CLIENT_SECRET=<your-paypal-secret>

1. Run the Development Server:

Start the development server to see your client application in action:

npm start

The application should open in your default browser at http://localhost:3000.

For production, you might want to build the application by running:

npm run build

Custom Checkout Page (Frontend)

UnipayConnect lets you build a custom checkout page like Stripe's. Here’s an example of a form using React Hook Form and Tailwind CSS:

import { useForm } from "react-hook-form";

const CheckoutForm = ({ products, totalAmount }) => {
  const { register, handleSubmit } = useForm();

  const onSubmit = async (data) => {
    console.log(data);
    // Add your submit logic here
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="checkout-form">
      <div className="col-left">
        <input {...register("name")} placeholder="Name" className="input" />
        <input {...register("email")} placeholder="Email" className="input" />
        <input {...register("amount")} placeholder="Amount" className="input" />
        {/* Add more fields as necessary */}
      </div>
      <div className="col-right">
        <h2>Order Summary</h2>
        {products.map((product, index) => (
          <div key={index}>
            {product.name} - ${product.price * product.quantity}
          </div>
        ))}
        <div>Total: ${totalAmount}</div>
      </div>
      <button type="submit" className="submit-button">
        Pay Now
      </button>
    </form>
  );
};

• Customize Payment Providers (Radio Buttons) If you want users to select a provider (Stripe, PayPal, Razorpay), you can add radio buttons:

<div>
  <label>
    <input {...register("provider")} type="radio" value="stripe" /> Stripe
  </label>
  <label>
    <input {...register("provider")} type="radio" value="paypal" /> PayPal
  </label>
  <label>
    <input {...register("provider")} type="radio" value="razorpay" /> Razorpay
  </label>
</div>

• Test Card Numbers You can find respective test card numbers of payment providers on their website itself.

Postman Collection

Use our Postman collection to test API endpoints: Postman

Conclusion

UnipayConnect simplifies payments across multiple providers. Whether it's creating checkout sessions, capturing payments, or verifying webhooks, it provides an easy way to integrate and manage multiple payment gateways without getting into their complex APIs.

Feel free to contribute or raise issues in the repository! 🧡