Monnify Web Checkout

Table of Content

1 Table of Content
2 Overview
3 Adding the Monnify Checkout to Your Website
- 3.1 Response Object
- 3.2 User Cancelled Response
- 3.3 Field Reference

Overview

Readily implement the Monnify Checkout Page on your websites to enable your customers to make payments on your platform. Monnify Checkout Page provides your customers with various payment method options such as:

Pay with Transfer
Pay with Card
Pay with USSD
Pay with Phone Number

Web SDK Checkout Page

Adding the Monnify Checkout to Your Website

Installing the Monnify Checkout Page is very easy and can be done by adding the checkout Javascript snippet to your website by copying the snippet code as shown below:

<html>
<head>
    <script type="text/javascript" src="https://sdk.monnify.com/plugin/monnify.js"></script>
    <script>
        function payWithMonnify() {
            MonnifySDK.initialize({
                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);
                }
            });
        }
    </script>
</head>

<body>
    <div>
        <button type="button" onclick="payWithMonnify()">Pay With Monnify</button>
    </div>
</body>
</html>

You will need to pass in your contract code and api key when initializing the SDK. Your contract code and api key can be found on your monnify dashboard by navigating to the developer section.

Response Object

When the transaction is completed, Monnify will return a response object to your onComplete function.

{
    "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"
}

It is recommended that you always make a get transaction status call whenever a transaction is completed (or canceled) before saving the transaction on your database. Monnify will also notify you via your webhook URL of the status of any transaction.

User Cancelled Response

If a user cancels, Monnify returns the following response to your onClose function

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

Field Reference

This shows the description for the fields in the request body.

Field	Mandatory(M)/Optional(O)	Description

Field	Mandatory(M)/Optional(O)	Description
amount	M	The amount be paid by the customer
currency	M	The currency of the transaction being initialized (“NGN“)
reference	M	Merchant’s unique reference for every transaction. (The SDK already has a code snippet that generates this for you, but you can always replace it)
customerName	M	This field contains the full name of the customer
customerEmail	M	Email address of the customer
apiKey	M	Merchant’s API Key
contractCode	M	Merchant’s Contract Code
paymentDescription	M	Description for the transaction. Will be used as the account name for bank transfer payments
incomeSplitConfig	O	Object containing specifications on how payments to this reserve account should be split.
onLoadStart	O	This allows you the flexibility of performing an action when the SDK is about to start
onLoadComplete	O	This allows the flexibility of performing an action when the SDK has been loaded fully and payment methods displayed
onComplete	O	This field allows you to implement what should happen when a transaction is completed
onClose	O	This field allows you to implement what should happen when the modal is completed

By default, all payment methods are displayed. However, if you want to control the displayed payment methods, you can do so by setting paymentMethods field in the initialization request as seen below:

If the paymentMethods property isn’t included, by default, all the available payment methods will be displayed to your customers. If the paymentMethods property is specified, the listed payment methods will be displayed to your customers, see sample below: