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:  "[e-mail]",
    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": "[e-mail]",
    "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:  "[e-mail]",
			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:  '[e-mail]',
				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:  '[e-mail]',
			paymentDescription:  'Payment for services',
			metadata: {
				'customData':  'Some custom data',
			},
		});
	}
}