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:

  1. Pay with Transfer

  2. Pay with Card,

  3. Pay with USSD,

  4. 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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 <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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "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

1 2 3 4 5 6 7 { "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


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

1 <script type="text/javascript" src="https://sdk.monnify.com/plugin/monnify.js"></script>

Version 2 (Latest Version)

1 <script type="text/javascript" src="https://sdk-v2.monnify.com/plugin/monnify.js"></script>

What’s Changed from Version 1?

The main areas of change are as follows:

  1. The javascript URL changed from

Version 1

1 <script type="text/javascript" src="https://sdk.monnify.com/plugin/monnify.js"></script>

Version 2 (Latest Version)

1 <script type="text/javascript" src="https://sdk-v2.monnify.com/plugin/monnify.js"></script>

 

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.

1 2 3 4 ... onLoadStart: () => { console.log("loading has started"); },

 

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:

1 2 3 4 5 6 7 8 9 10 ... paymentMethods: [ "CARD", "ACCOUNT_TRANSFER", "USSD", "PHONE_NUMBER" ], onLoadStart: () => { console.log("loading has started"); },

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:

1 2 3 4 5 6 7 8 ... paymentMethods: [ "USSD", "PHONE_NUMBER" ], onComplete: function(response) { console.log(response); },

 

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.