Via Mono Widget

Integration Guide

To easily integrate Directpay via the widget into your current solution, please proceed with the following steps:

Step 1: Make an API call to our Initiate Payments API
Step 2: Instantiate the Directpay widget with the Payment ID
Step 3: Verify payments via Webhooks or our Verify API

Step 1: Make an API call to our Initiate Payments API

The first step to take will be to call our Initiate Payments API. The reason for taking this step is to get our Payment ID from our API response so we can easily pass this to the direct page widget for authorisation from your customers.

Be it for a one-time or recurring debit, ensure to pass in these required fields such as your amount (in Kobo), payment type (one-time or recurring), a unique reference id (i.e minimum of 10 unique digits), a payment description to inform your user the purpose of this debit and your secret key in your headers which can be gotten from your already existing dashboard application.

Other non-required fields include an Account ID field, a redirect URL field (i.e to redirect users after a successful or failed payment; check here for more info) and a meta-object for extra payload information.

📘
NOTE
On your directpay widget, you can use packages such as axios or node-fetch to call this API, then proceeding to send the Payment ID to your Directpay widget for completion as explained in Step 2.

API Reference ➡

curl --request POST \
     --url https://api.withmono.com/v1/payments/initiate \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'mono-sec-key: test_sk_from_your_dashboard' \
     --data '
{
     "amount": "500000",
     "type": "onetime-debit",
     "description": "For new pair of sneakers",
     "reference": "REF-visitor-001",
}
'

{
    "id": "txreq_HeqMWnpWVvzdpMXiB4I123456",
    "type": "onetime-debit",
    "amount": 500000,
    "description": "For new pair of sneakers",
    "reference": "REF-visitor-001",
    "payment_link": "https://connect.withmono.com/?key=live_pk_fpfebMqDkCUOAPl54656&scope=payments&data=%7B%22amount%22%3A20124%2C%22description%22%3A%22On%20pilotxxx%22%2C%22type%22%3A%22onetime-debit%22%2C%22redirect_url%22%3A%22mono.co%22%2C%22reference%22%3A%22testing-monefy-visitor0%22%7D",
    "created_at": "2022-04-05T18:54:22.915Z",
    "updated_at": "2022-04-05T18:54:22.915Z"
}

Step 2: Instantiate the Directpay widget with the Payment ID

With step one out of the way, we can now proceed with this step to instantiate our Directpay widget.

What you simply need to do here is to update your Directpay data callback in your widget with the Payment ID field, which you have already received from Step 1 above and your scope callback to payments.

Upon payment successful completion from your customer, we can now move over to the next step.

Callback Reference ➡

...
...

const monoWidget = new Connect({
  key: "live_pk_from_your_dashboard",
  scope: "payments",
  data: {
    payment_id: "txreq_HeqMWnpWVvzdpMXiB4I123456"
  }
});

monoWidget.setup();
monoWidget.open()

Step 3: Verify payments via Webhooks or our Verify API

In this step, your customer is assumed to have completed payment whether successful or failed. Payments verification can now be done in two ways via:

Webhook Events.
Verify Payment Status API.

Webhook Events.

With this out of the way, as soon as your customer authorises payments from their respective bank accounts via the Directpay widget, and it's either successful or failed, webhook events will be sent to this effect.

The various webhook events that get sent irrespective of a one-time or recurring payments can be found on our documentation page here.

🚧
NOTE

It is important to have a Webhook URL added to your Mono dashboard application. Not ensuring so would enable your business to not be aware of real-time webhook event notifications from your customers for both successful or failed payments.

Please check out this guide here on how to set up a webhook URL.

🚧
Verifying Payment
Please ensure to verify the payment status via the verify payment endpoint before proceeding to give value for the payment.

Verify Payment Status API.

Another alternative to verify payments from your customers is via their payment reference. This reference can be passed to the body request of our Verify Payments Status API to get the current status and customer information of any Directpay payment. Please don't forget to pass your Mono app secret key to your headers.

API Reference ➡

curl --request POST \
     --url https://api.withmono.com/v1/payments/verify \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'mono-sec-key: sdfsdfdsdffd' \
     --data '
{
     "reference": "REF-visitor-001"
}
'

{
    "type": "onetime-debit",
    "data": {
        "_id": "61faab668fc6656c1420a1e7",
        "id": "txreq_HeqMWnpWVvzdpMXiB4I123456",
        "status": "successful",
        "message": "Payment was successful",
        "amount": 500000,
        "description": "For new pair of sneakers",
        "fee": 4500,
        "currency": "NGN",
        "account": {
            "_id": "61faab668fc66123456",
            "institution": {
                "name": "KudaBank",
                "bankCode": "090267",
                "type": "PERSONAL_BANKING"
            },
            "name": "KING  KENWAYDAVIDSON",
            "type": "DIGITAL_SAVINGS_ACCOUNT",
            "accountNumber": "2002123456",
            "balance": 93707,
            "currency": "NGN",
            "bvn": "21234567890",
            "liveMode": true,
            "timeline": "61faaac08fc6656c142123456",
            "created_at": "2022-02-02T16:03:50.408Z",
            "updated_at": "2022-02-10T21:00:57.321Z"
        },
        "customer": null,
        "reference": "REF-visitor-001",
        "created_at": "2022-02-02T16:03:50.743Z",
        "updated_at": "2022-02-02T16:04:24.651Z"
    }
}