monnify-js
Version:
A Javascript wrapper for the Monnify SDK
299 lines (246 loc) • 7.84 kB
Markdown
# 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:
```bash
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:
```javascript
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:
```javascript
monnify.initializePayment({
amount: 100,
currency: "NGN",
reference: new String((new Date()).getTime()),
customerFullName: "Damilare Ogunnaike",
customerEmail: "ogunnaike.damilare@gmail.com",
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:
```javascript
{
"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": "ogunnaike.damilare@gmail.com",
"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:
```javascript
{
"authorizedAmount": 30,
"paymentStatus": "USER_CANCELLED",
"redirectUrl": null,
"responseCode": "USER_CANCELLED",
"responseMessage": "User cancelled Transaction"
}
```
## React Usage
### MonnifyButton.jsx
```javascript
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: "john.doe@example.com",
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
```javascript
<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: 'john.doe@example.com',
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
```typescript
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
```typescript
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: 'john.doe@example.com',
paymentDescription: 'Payment for services',
metadata: {
'customData': 'Some custom data',
},
});
}
}
```