Monnify SDK Node.js Package

The Monnify Web SDK is now available as a Node.js package, offering an easy and efficient way to integrate payment gateway solutions into your web applications. Specifically designed for developers using React, Vue.js, Next.js and and any modern JavaScript framework for web, this package simplifies the process of accepting payments online. It allows you to quickly implement secure and reliable payment functionalities, ensuring a seamless experience for your users. With the Monnify Node.js package, you can effortlessly integrate various payment channels into your web projects, making payment management both scalable and straightforward.

To integrate the Monnify Web SDK Node.js package into your React or Next.js project using TypeScript, follow the installation and setup process outlined below. This will enable you to effortlessly accept payments on the web with a secure and seamless experience.

Prerequisites

1. Node.js and npm/yarn Installed: Ensure you have Node.js and either npm or yarn installed on your development machine. React or Next.js Project with TypeScript: Have an existing React or Next.js project configured with TypeScript. Monnify Account and API Credentials: Sign up for a Monnify account and obtain your API credentials (API Key, Secret, and Contract Code) from the Monnify dashboard.

2. Install the Monnify SDK Use npm or yarn to install the Monnify Web SDK package into your project.

Using npm:

npm install @adsesugh/monnify-sdk --save

Using yarn:

yarn add @adsesugh/monnify-sdk

3. Configure Environment Variables For security reasons, it's best to store sensitive information like API credentials in environment variables.

Create a .env File: In the root directory of your project, create a .env file (or .env.local for Next.js projects). Add Your Credentials:

MONNIFY_API_KEY=your_monnify_api_key
MONNIFY_API_SECRET=your_monnify_api_secret
MONNIFY_CONTRACT_CODE=your_monnify_contract_code
MONNIFY_ENVIRONMENT=TEST # Use 'LIVE' for production

Note for Next.js Users: Prefix environment variables with NEXT_PUBLIC_ to make them accessible on the client side. For React projects, ensure your build setup supports environment variables appropriately.

4. Initialize and Use the Monnify SDK in Your Code Integrate the Monnify SDK into your React or Next.js components where you want to handle payments.

Usage

1. Example: Payment Button Component in TypeScript for React/Next.js Application

• One time payment without amount splitting to subaccount

// For React/Next.js Application

import React from 'react';
import { Monnify } from '@adsesugh/monnify-sdk';

const monnify = new Monnify({
   publicKey: process.env.MONNIFY_API_KEY!,
   contractCode: process.env.MONNIFY_CONTRACT_CODE!,
   mode: process.env.MONNIFY_ENVIRONMENT === 'LIVE' ? 'LIVE' : 'TEST',
})

const PaymentButton: React.FC = () => {

    const handlePayment = async () => {
      try {
         const res = await monnify.initializePayment({
            amount: 500,
            currency: 'NGN',
            reference: `${new String(new Date().getTime())}`,
            customerName: 'Sesugh Daniel',
            customerEmail: '[email protected]',
            paymentDescription: 'Test Payment',
            redirectUrl: 'https://example.com/payment-success'
         });
         console.log('Payment successful:', res);
      } catch (error) {
         console.error('Payment failed:', error);
      }
    };

   return (
        <button onClick={handlePayment}>
            Pay with Monnify
        </button>
   );
};

export default PaymentButton;

• One time payment with split amount to subaccount

// For React/Next.js Application

import React from 'react';
import { Monnify } from '@adsesugh/monnify-sdk';

const monnify = new Monnify({
   publicKey: process.env.MONNIFY_API_KEY!,
   contractCode: process.env.MONNIFY_CONTRACT_CODE!,
   mode: process.env.MONNIFY_ENVIRONMENT === 'LIVE' ? 'LIVE' : 'TEST',
})

const PaymentButton: React.FC = () => {

    const handlePayment = async () => {
      try {
         const res = await monnify.initializePayment({
            amount: 500,
            currency: 'NGN',
            reference: `${new String(new Date().getTime())}`,
            customerName: 'Sesugh Daniel',
            customerEmail: '[email protected]',
            paymentDescription: 'Test Payment',
            redirectUrl: 'https://example.com/payment-success',
            incomeSplitConfig: [
                {
                  feeBearer: true,
                  subAccountCode: 'the subaccount',
                  feePercentage: 0.5,
                  splitAmount: 5000
               },{
                //more subaccount
               }
            ]
         });
         console.log('Payment successful:', res);
      } catch (error) {
         console.error('Payment failed:', error);
      }
    };

   return (
        <button onClick={handlePayment}>
            Pay with Monnify
        </button>
   );
};

export default PaymentButton;

Example: Payment Button Component in TypeScript for Vue.js 3 Application

• One time payment without amount splitting to subaccount

<template>
   <button @click="handlePayment">Pay Now</button>
</template>
<script setup lang='ts'>
   import { Monnify } from '@adsesugh/monnify-sdk';

  const monnify = new Monnify({
      publicKey: process.env.MONNIFY_API_KEY!,
      contractCode: process.env.MONNIFY_CONTRACT_CODE!,
      mode: process.env.MONNIFY_ENVIRONMENT === 'LIVE' ? 'LIVE' : 'TEST',
  })
  
  async function handlePayment() {
    try {
      const res = await monnify.initializePayment({
        amount: 500,
        currency: 'NGN',
        reference: `${new String(new Date().getTime())}`,
        customerName: 'Sesugh Daniel',
        customerEmail: '[email protected]',
        paymentDescription: 'Test Payment',
        redirectUrl: 'https://example.com/payment-success'
      });
      console.log('Payment successful:', res);
    } catch (error) {
      console.error('Payment failed:', error);
    }
  }
</script>

• One time payment with split amount to subaccount

<template>
   <button @click="handlePayment">Pay Now</button>
</template>
<script setup lang='ts'>
   import { Monnify } from '@adsesugh/monnify-sdk';

  const monnify = new Monnify({
      publicKey: process.env.MONNIFY_API_KEY!,
      contractCode: process.env.MONNIFY_CONTRACT_CODE!,
      mode: process.env.MONNIFY_ENVIRONMENT === 'LIVE' ? 'LIVE' : 'TEST',
  })
  
  async function handlePayment() {
    try {
      const res = await monnify.initializePayment({
        amount: 500,
        currency: 'NGN',
        reference: `${new String(new Date().getTime())}`,
        customerName: 'Sesugh Daniel',
        customerEmail: '[email protected]',
        paymentDescription: 'Test Payment',
        redirectUrl: 'https://example.com/payment-success', 
         incomeSplitConfig: [
            {
               feeBearer: true,
               subAccountCode: 'the subaccount',
               feePercentage: 0.5,
               splitAmount: 5000
            },{
               //more subaccount
            }
         ]
      });
      console.log('Payment successful:', res);
    } catch (error) {
      console.error('Payment failed:', error);
    }
  }
</script>

Explanation of the Code:

• Importing Monnify: The Monnify SDK is imported to access its functionalities.

• Initializing Monnify: The Monnify.initializePayment method is called with a configuration object containing:

• amount: The payment amount in the smallest currency unit.

• currency: The currency code (e.g., 'NGN' for Nigerian Naira).

• reference: A unique transaction reference. It's essential to ensure uniqueness to track payments accurately.

• customerName & customerEmail: Details of the customer making the payment.

• apiKey & contractCode: Your Monnify API credentials sourced from environment variables.

• environment: Specifies whether to use the 'TEST' or 'LIVE' environment.

Callbacks:

• onComplete: Triggered when the payment is successful.
• onClose: Triggered when the payment window is closed without completing the payment.
• onError: Triggered when there's an error during the payment process.
• Button Element: A simple button that, when clicked, initiates the payment process by calling handlePayment.

6. Run and Test Your Application Start your development server and test the payment integration.

Using npm:

npm run dev

Using yarn:

yarn dev

Navigate to the component/page containing the payment button, and attempt a test payment to ensure everything functions as expected.

6. Handle Server-Side Verification (Optional but Recommended) For enhanced security and to confirm payments reliably, set up server-side verification using Monnify's webhook system. This involves:

Setting Up a Server Endpoint: Create an API route in Next.js or an endpoint in your backend to receive webhook notifications from Monnify. Verifying Payment Data: Upon receiving a webhook, verify the payment details, update order statuses, and perform necessary business logic. Refer to Monnify's official documentation for detailed guidance on setting up and securing webhooks.

7. Additional Customizations and Configurations Depending on your project's requirements, you might want to customize the payment flow further. Consider:

Styling the Payment Widget: Customize the appearance of the Monnify payment window to match your application's theme. Handling Different Payment Channels: Configure and handle various payment channels supported by Monnify, such as cards, bank transfers, mobile money, etc. Error Handling and Notifications: Implement comprehensive error handling and user notifications to improve the user experience during payment processes.

Summary

By following the steps above, you can seamlessly install and integrate the Monnify Web SDK Node.js package into your React or Next.js project using TypeScript. This setup facilitates easy and secure payment gateway integration, allowing you to accept payments on the web with minimal effort.

Thank you.