Monnify-Js

A simple JavaScript wrapper for integrating with the Monnify payment gateway. This library allows you to easily configure and initialize payments using the Monnify Web SDK.

Installation

First, install the package:

npm  install  monnify-js

Usage

Import and Initialize

To use the Monnify wrapper, you need to create an instance with your Monnify API key and contract code:

import  Monnify  from  'monnify-js';

const  monnify = new  Monnify('YOUR_API_KEY', 'YOUR_CONTRACT_CODE');

Initializing a Payment

To initialize a payment, call the initializePayment method with a PaymentRequest object:

monnify.initializePayment({
    amount:  100,
    currency:  "NGN",
    reference:  new  String((new  Date()).getTime()),
    customerFullName:  "Damilare Ogunnaike",
    customerEmail:  "[email protected]",
    apiKey:  "MK_PROD_FLX4P92EDF",
    contractCode:  "626609763141",
    paymentDescription:  "Lahray World",
    metadata:  {
        "name":  "Damilare",
        "age":  45
    },
    incomeSplitConfig:  [
    {
        "subAccountCode":  "MFY_SUB_342113621921",
        "feePercentage":  50,
        "splitAmount":  1900,
        "feeBearer":  true
    },  
    {
        "subAccountCode":  "MFY_SUB_342113621922",
        "feePercentage":  50,
        "splitAmount":  2100,
        "feeBearer":  true
    }],
    onLoadStart:  ()  =>  {
        console.log("loading has started");
    },
    onLoadComplete:  ()  =>  {
        console.log("SDK is UP");
    },
    onComplete:  function(response)  {
        //Implement what happens when the transaction is completed.
        console.log(response);
    },
    onClose:  function(data)  {
        //Implement what should happen when the modal is closed here
        console.log(data);
    }
  });

PaymentRequest Object

| Field | Type | Required | Description | | -- | -- | -- | -- | | amount | number | Yes | Amount to be paid in decimal (e.g 100.50). | | currency | string | Yes | Currency code (e.g., 'NGN'). | | reference | string | Yes | Unique reference for the payment transaction. | | customerFullName | string | Yes | Full name of the customer making the payment. | | customerEmail | string | Yes | Email address of the customer. | | paymentDescription | string | Yes | Description of the payment. | | redirectUrl | string | No | URL to redirect to after payment completion. | | paymentMethods | Array<string> | No | List of payment methods to display (e.g., 'CARD', 'ACCOUNT_TRANSFER'). Defaults to all methods i.e. [ "CARD", "ACCOUNT_TRANSFER" , "USSD", "PHONE_NUMBER" ]. | | metadata | Object | No | Additional metadata for the transaction. | | incomeSplitConfig | Array<Object> | No | Configuration for splitting payments between sub-accounts. | | onLoadStart | function | No | Callback function executed when Monnify SDK starts loading. | | onLoadComplete | function | No | Callback function executed when Monnify SDK is loaded and ready. | | onComplete | function | No | Callback function executed on successful completion of the transaction. | | onClose | function | No | Callback function executed when the payment modal is closed or canceled. |

Example Payment Response

The onComplete function provides a PaymentResponse object with details about the transaction:

{
    "amount": 100,
    "amountPaid": 100,
    "completed": true,
    "completedOn": "2022-03-31T10:53:50.000+0000",
    "createdOn": "2022-03-31T10:52:09.000+0000",
    "currencyCode": "NGN",
    "customerEmail": "[email protected]",
    "customerName": "Damilare Ogunnaike",
    "fee": 10.75,
    "metaData": {
        "deviceType":  "mobile",
        "ipAddress":  "127.0.0.1"
    },
    "payableAmount": 100,
    "paymentMethod": "CARD",
    "paymentReference": "MNFY|PAYREF|GENERATED|1648723909057299503",
    "paymentStatus": "PAID",
    "transactionReference": "MNFY|67|20220331115209|000063"
}

Example User Cancelled Response

The onClose function provides a UserCancelledResponse object if the user cancels the transaction:

{
    "authorizedAmount": 30,
    "paymentStatus": "USER_CANCELLED",
    "redirectUrl": null,
    "responseCode": "USER_CANCELLED",
    "responseMessage": "User cancelled Transaction"
}

React Usage

MonnifyButton.jsx

import  React  from  "react";
import  Monnify  from  "monnify-js";

function  MonnifyButton() {
	const  monnify  =  new  Monnify("MY_API_KEY", "MY_CONRACT_CODE");

	function  pay() {
		monnify.initializePayment({
			amount:  500,
			currency:  "NGN",
			reference:  new  Date().getTime(),
			customerFullName:  "John Doe",
			customerEmail:  "[email protected]",
			paymentDescription:  "Payment for services",
			metadata: {
				'customData':  "Some custom data",
			},
			onLoadStart: () => {
				console.log("Monnify SDK loading started");
			},
			onLoadComplete: () => {
				console.log("Monnify SDK is ready");
			},
			onComplete: (response) => {
				console.log("Transaction complete:", response);
			},
			onClose: (response) => {
				console.log("Payment modal closed:", response);
			},
		});
	}
	return  <button  onClick={() =>  pay()}>Pay with Monnify</button>;
}
export  default  MonnifyButton;

Vue Usage

MonnifyButton.vue

<script>
import  Monnify  from  'monnify-js'

export  default {
	data() {
		return {
			monnify:  new  Monnify('MY_API_KEY', 'MY_CONTRACT_CODE'),
		}
	},

	methods: {
		initializePayment() {
			this.monnify.initializePayment({
				amount:  5000
				currency:  'NGN',
				reference:  new  Date().getTime(),
				customerFullName:  'John Doe',
				customerEmail:  '[email protected]',
				paymentDescription:  'Payment for services',
				metadata: {
					'customData':  'Some custom data',
				},
				onLoadStart: () => {
					console.log('Monnify SDK loading started')
				},
				onLoadComplete: () => {
					console.log('Monnify SDK is ready')
				},
				onComplete:  response  => {
					console.log('Transaction complete:', response)
				},
				onClose:  response  => {
					console.log('Payment modal closed:', response)
				},
			})
		},
	},
}
</script>

<template>
	<button @click="initializePayment">Pay with Monnify</button>
</template>

Angular Usage

monnify.service.ts

import { Injectable } from  '@angular/core';
import  Monnify  from  'monnify-js';

@Injectable({
	providedIn:  'root'
})

export  class  MonnifyService {
	private  monnify  =  new  Monnify('MY_API_KEY', 'MY_CONTRACT_CODE');

	initializePayment(paymentRequest:  any):  void {
		this.monnify.initializePayment({
			...paymentRequest,
			onLoadStart: () => {
				console.log('Monnify SDK loading started');
			},
			onLoadComplete: () => {
				console.log('Monnify SDK is ready');
			},
			onComplete: (response:  any) => {
				console.log('Transaction complete:', response);
			},
			onClose: (response:  any) => {
				console.log('Payment modal closed:', response);
			},
		});
	}
}

monnify.button.ts

import { Component } from  '@angular/core';
import { MonnifyService } from  './monnify.service';

@Component({
	selector:  'monnify-button',
	standalone:  true,
	template:  `<button  (click)="payWithMonnify()">Pay with Monnify</button>`,
})

export  class  MonnifyButton {
	constructor(private  monnifyService:  MonnifyService) {}
	  
	payWithMonnify():  void {
		this.monnifyService.initializePayment({
			amount:  100,
			currency:  'NGN',
			reference:  new  Date().getTime(),
			customerFullName:  'John Doe',
			customerEmail:  '[email protected]',
			paymentDescription:  'Payment for services',
			metadata: {
				'customData':  'Some custom data',
			},
		});
	}
}