Monnify Checkout Page Web SDK V2
Table of Content
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.
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-v2.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_FLX4P92BJF",
contractCode: "626689863141",
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": "smart@example.com",
"customerName": "Smart Mekiliuwa",
"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 |
|---|---|---|
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 |
How to Migrate from Version 1 to Version 2
Change the Monnify Web SDK Javascript snippet on your website by changing the javascript type URL of version 1 to that of version 2.
Version 1
Version 2 (Latest Version)
What’s Changed from Version 1?
The main areas of change are as follows:
The javascript URL changed from
Version 1
Version 2 (Latest Version)
2. OnLoadStart function was added
This allows you the flexibility of performing an action when the SDK is about to start. You can define whatever trigger you want to happen when the SDK is about to be launched.
3. OnLoadComplete function was added
This allows the flexibility of performing an action when the SDK has been loaded fully and payment methods displayed. You can define whatever trigger you want to happen immediately after the SDK has loaded fully.
4. Two new payment methods were added
The newly added payment methods are Pay with Phone Number and Pay with USSD. Version 2 has four(4) payment methods available for collections;
CARD
ACCOUNT_TRANSFER
USSD
PHONE_NUMBER
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 id specified, the listed payment methods will be displayed to your customers, see sample below:
5. The isTestMode field has been removed from version 1 which was used to indicate your active environment (whether live or test). The active environment will be automatically detected using the apiKey specified by you in the javascript snippet.