Plutu Node.js TypeScript SDK

A comprehensive TypeScript SDK for interacting with the Plutu payment gateway. This SDK provides easy-to-use services for various Plutu payment gateways, including Adfali, Sadad, Local Bank Cards, Tlync, and MPGS. It ensures structured response handling, robust validation, and seamless integration into your Node.js applications.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
  • PlutuAdfali
  • PlutuSadad
  • PlutuLocalBankCards
  • PlutuTlync
  • PlutuMpgs
• Express Server Setup
• Environment Variables
• Testing
• Contributing
• License

Features

• Multiple Gateways Support: Interact with various Plutu payment gateways such as Adfali, Sadad, Local Bank Cards, Tlync, and MPGS.
• Structured Responses: Handle API responses consistently with structured response classes.
• Robust Validation: Validate input parameters to prevent invalid API calls.
• Error Handling: Gracefully handle API-level errors without relying on exceptions.
• Easy Integration: Simple and intuitive API for seamless integration into your Node.js applications.
• Express Integration: Example setup for handling callbacks using Express.

Prerequisites

• Node.js: Version 14.x or higher.
• npm: Version 6.x or higher.

Installation

Install the SDK via npm:

npm install plutu-node

Configuration

Before using the SDK, set up the necessary environment variables. You can use a .env file for local development.

Environment Variables

Create a .env file in your project's root directory and add the following variables:

PLUTU_API_KEY=your_plutu_api_key
PLUTU_ACCESS_TOKEN=your_plutu_access_token
PLUTU_SECRET_KEY=your_plutu_secret_key

• PLUTU_API_KEY: Your Plutu API key.
• PLUTU_ACCESS_TOKEN: Your Plutu access token.
• PLUTU_SECRET_KEY: Your Plutu secret key for hashing.

Usage

Import the necessary services from the SDK and utilize them in your application. Below are examples demonstrating how to use each service.

PlutuAdfali

Example: Verifying and Confirming a Payment

import { PlutuAdfali } from "plutu-node";
import dotenv from "dotenv";

dotenv.config();

async function testPlutuAdfali() {
  const mobileNumber = "0913632323";
  const amount = 10;
  const code = "1111";
  const invoiceNo = "1234";
  
  try {
    // Step 1: Verify Payment
    const verifyResponse = await PlutuAdfali.verify(mobileNumber, amount);
    
    if (verifyResponse.getOriginalResponse().isSuccessful()) {
      const processId = verifyResponse.getProcessId()!;
      console.log(`Process ID: ${processId}`);
      
      // Step 2: Confirm Payment
      const confirmResponse = await PlutuAdfali.confirm(
        processId,
        code,
        amount,
        invoiceNo
      );

      if (confirmResponse.getOriginalResponse().isSuccessful()) {
        console.log("Payment confirmed successfully");
      } else if (confirmResponse.getOriginalResponse().hasError()) {
        const errorCode = confirmResponse.getOriginalResponse().getErrorCode();
        const errorMessage = confirmResponse.getOriginalResponse().getErrorMessage();
        console.error(`Error: ${errorCode} - ${errorMessage}`);
      }
    } else if (verifyResponse.getOriginalResponse().hasError()) {
      const errorCode = verifyResponse.getOriginalResponse().getErrorCode();
      const errorMessage = verifyResponse.getOriginalResponse().getErrorMessage();
      console.error(`Verify Error ${errorCode}: ${errorMessage}`);
    }
  } catch (error: any) {
    console.error("Unexpected Error:", error);
  }
}

testPlutuAdfali();

PlutuSadad

Example: Verifying and Confirming a Payment

import { PlutuSadad } from "plutu-node";
import dotenv from "dotenv";

dotenv.config();

async function testPlutuSadad() {
  const mobileNumber = "0913632323";
  const birthYear = 1990;
  const amount = 100.0;
  const code = "111111";
  const invoiceNo = "INV789";

  try {
    // Step 1: Verify Payment
    const verifyResponse = await PlutuSadad.verify(
      mobileNumber,
      birthYear,
      amount
    );

    if (verifyResponse.getOriginalResponse().isSuccessful()) {
      const receivedProcessId = verifyResponse.getProcessId()!;
      console.log(`Process ID: ${receivedProcessId}`);

      // Step 2: Confirm Payment
      const confirmResponse = await PlutuSadad.confirm(
        receivedProcessId,
        code,
        amount,
        invoiceNo
      );

      if (confirmResponse.getOriginalResponse().isSuccessful()) {
        console.log("Payment confirmed successfully");
      } else if (confirmResponse.getOriginalResponse().hasError()) {
        const errorCode = confirmResponse.getOriginalResponse().getErrorCode();
        const errorMessage = confirmResponse.getOriginalResponse().getErrorMessage();
        console.error(`Confirm Error ${errorCode}: ${errorMessage}`);
      }
    } else if (verifyResponse.getOriginalResponse().hasError()) {
      const errorCode = verifyResponse.getOriginalResponse().getErrorCode();
      const errorMessage = verifyResponse.getOriginalResponse().getErrorMessage();
      console.error(`Verify Error ${errorCode}: ${errorMessage}`);
    }
  } catch (error: any) {
    console.error("Unexpected Error:", error);
  }
}

testPlutuSadad();

PlutuLocalBankCards

Example: Confirming a Payment

import { PlutuLocalBankCards } from "plutu-node";
import dotenv from "dotenv";

dotenv.config();

const returnUrl = `${process.env.APP_URL}/payment/return`;

async function testPlutuLocalBankCards() {
  const amount = 100.0;
  const invoiceNo = "INV123";

  try {
    const confirmResponse = await PlutuLocalBankCards.confirm(
      amount,
      invoiceNo,
      returnUrl,
      "en"
    );
    
    console.log(confirmResponse);
    
    if (confirmResponse.getOriginalResponse().isSuccessful()) {
      console.log("Payment confirmed successfully");
      console.log(`Redirect URL: ${confirmResponse.getRedirectUrl()}`);
      // Redirect the user to the provided URL
    } else {
      console.log(confirmResponse.getOriginalResponse().getErrorMessage());
    }
  } catch (error: any) {
    console.error("Unexpected Error:", error);
  }
}

testPlutuLocalBankCards();

PlutuTlync

Example: Confirming a Payment

import { PlutuTlync } from "plutu-node";
import dotenv from "dotenv";

dotenv.config();

const returnUrl = `${process.env.APP_URL}/payment/return`;

async function testPlutuTlync() {
  const mobileNumber = "0910441322";
  const amount = 150.0;
  const invoiceNo = "INV123";
  const callbackUrl = "https://webhook.site/your-webhook-url";

  try {
    const confirmResponse = await PlutuTlync.confirm(
      mobileNumber,
      amount,
      invoiceNo,
      returnUrl,
      callbackUrl,
      "en"
    );
    
    if (confirmResponse.getOriginalResponse().isSuccessful()) {
      console.log("Payment confirmed successfully");
      console.log("Redirect URL:", confirmResponse.getRedirectUrl());
      // Redirect the user to the provided URL
    } else {
      console.log(confirmResponse.getOriginalResponse().getErrorMessage());
    }
  } catch (error: any) {
    console.error("Unexpected Error:", error);
  }
}

testPlutuTlync();

PlutuMpgs

Example: Confirming a Payment

import { PlutuMpgs } from "plutu-node";
import dotenv from "dotenv";

dotenv.config();

const returnUrl = `${process.env.APP_URL}/payment/return`;

async function testPlutuMpgs() {
  const amount = 200.0;
  const invoiceNo = "INV456";

  try {
    const confirmResponse = await PlutuMpgs.confirm(
      amount,
      invoiceNo,
      returnUrl,
      "ar"
    );
    
    if (confirmResponse.getOriginalResponse().isSuccessful()) {
      console.log("Payment confirmed successfully");
      console.log("Redirect URL:", confirmResponse.getRedirectUrl());
      // Redirect the user to the provided URL
    } else {
      console.log(confirmResponse.getOriginalResponse().getErrorMessage());
    }
  } catch (error: any) {
    console.error("Unexpected Error:", error);
  }
}

testPlutuMpgs();

Express Server Setup

To handle callbacks from the Plutu payment gateways, you can set up an Express server with appropriate routes.

Example: Setting Up Callback Routes

import {
  PlutuAdfali,
  PlutuSadad,
  PlutuLocalBankCards,
  PlutuTlync,
  PlutuMpgs,
} from "plutu-node";
import dotenv from "dotenv";
import express from "express";

dotenv.config();

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

const returnUrl = `${process.env.APP_URL}/payment/return`;

// Callback route for PlutuLocalBankCards
app.get("/payment/return", async (req, res) => {
  try {
    const check = await PlutuLocalBankCards.callbackHandler(req.query);
    res.send(check);
  } catch (e) {
    res.status(400).send({
      error: "Invalid callback hash",
    });
  }
});

// Webhook route for PlutuTlync
app.post("/payment/webhook", async (req, res) => {
  try {
    const check = await PlutuTlync.callbackHandler(req.body);
    res.send(check);
  } catch (e) {
    res.status(400).send({
      error: "Invalid callback hash",
    });
  }
});

app.listen(3030, () => {
  console.log("Server is running on port 3030");
});

Explanation

• /payment/return: Handles GET requests from PlutuLocalBankCards , PlutuTlync , and PlutuMpgs after payment.
• /payment/webhook: Handles POST requests from PlutuTlync as webhooks.

Ensure your environment variables are correctly set in the .env file to match the APP_URL and Plutu credentials.

Express Server Setup

To handle callbacks from the Plutu payment gateways, set up an Express server with appropriate routes.

Example: Setting Up Callback Routes

import {
  PlutuAdfali,
  PlutuSadad,
  PlutuLocalBankCards,
  PlutuTlync,
  PlutuMpgs,
} from "plutu-node";
import dotenv from "dotenv";
import express from "express";

dotenv.config();

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

const returnUrl = `${process.env.APP_URL}/payment/return`;

// Callback route for PlutuLocalBankCards, PlutuTlync, and PlutuMpgs
app.get("/payment/return", async (req, res) => {
  try {
    const check = await PlutuLocalBankCards.callbackHandler(req.query);
    res.send(check);
  } catch (e) {
    res.status(400).send({
      error: "Invalid callback hash",
    });
  }
});

// Webhook route for PlutuTlync
app.post("/payment/webhook", async (req, res) => {
  try {
    const check = await PlutuTlync.callbackHandler(req.body);
    res.send(check);
  } catch (e) {
    res.status(400).send({
      error: "Invalid callback hash",
    });
  }
});

app.listen(3030, () => {
  console.log("Server is running on port 3030");
});

Explanation

• /payment/return: Handles GET requests from PlutuLocalBankCards , PlutuTlync , and PlutuMpgs after payment.
• /payment/webhook: Handles POST requests from PlutuTlync as webhooks.

Ensure your environment variables are correctly set in the .env file to match the APP_URL and Plutu credentials.

Environment Variables

The SDK relies on the following environment variables for configuration. Ensure these are set in your .env file or your deployment environment.

PLUTU_API_KEY=your_plutu_api_key
PLUTU_ACCESS_TOKEN=your_plutu_access_token
PLUTU_SECRET_KEY=your_plutu_secret_key

• PLUTU_API_KEY: Your Plutu API key.
• PLUTU_ACCESS_TOKEN: Your Plutu access token.
• PLUTU_SECRET_KEY: Your Plutu secret key used for hashing callbacks.

Contributing

Contributions are welcome! Please follow these steps to contribute:

1. Fork the Repository: Click the "Fork" button at the top right of the repository page.

2. Clone Your Fork:

   git clone https://github.com/melkmeshi/plutu-node.git
   cd plutu-node

3. Create a New Branch:

   git checkout -b feature/your-feature-name

4. Make Your Changes: Implement your feature or bug fix.

5. Commit Your Changes:

   git commit -m "Add feature XYZ"

6. Push to Your Fork:

   git push origin feature/your-feature-name

7. Create a Pull Request: Go to the original repository and create a pull request.

License

This project is licensed under the MIT License.

Additional Resources

• Plutu API Documentation
• Express.js Documentation
• TypeScript Documentation

Support

If you encounter any issues or have questions, feel free to open an issue on the GitHub repository or contact the maintainer at [email protected].

Happy Coding!