One-time Payment Guide

Get started by learning how to integrate DirectPay into your application. After finishing this guide you will be able to initiate transfer payments from your customer's bank account seamlessly.

Overview

To integrate Directpay into your web or mobile app, the following steps need to be taken:

• Initiate the payment request.

• Await and confirm payment from the Customer.

• Track or verify payment.

Prerequisites

Before you begin, make sure to complete the following essential steps:

• Register on the Mono dashboard. You can find a detailed guide here.
• Create an application with the product specified as "DirectPay" and obtain the associated secret key. Refer to the guide here for assistance.

Step 1: Initiate the payment request

You need to initiate the payment request via the API or Mono connect widget, which begins the payment process.

One-time payment

To initiate a one-time payment, an amount, type (i.e., onetime-debit), description, reference, account id (not required), and redirect URL can all be populated on the Initiate endpoint. Once all is provided, a payment link is generated, which your customers open in their browsers or on your mobile app in form of a web view.

API request

curl --request POST \
     --url https://api.withmono.com/v2/payments/initiate \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'mono-sec-key: test_sk_from_your_dashboard' \
     --data '
{
    "amount": 20000,
    "type": "onetime-debit",
    "description": "testing",
    "reference": "ref-00001-00007",
    "redirect_url": "https://mono.co",
    "customer": {
		"name": "Samuel Olamide",
        "email": "samuel@neem.co"
    }
}
'

API response

{
  "status": "successful",
  "message": "Payment Initiated Successfully",
  "data": {
    "id": "ODRPS87L0MBF",
    "mono_url": "https://checkout.mono.co/ODRPS87L0MBF",
    "type": "onetime-debit",
    "method": "account",
    "amount": 20000,
    "description": "testing",
    "reference": "ref-00001-00007",
    "customer": "661364ddc65fa5ad0981c842",
    "redirect_url": "https://mono.co",
    "created_at": "2024-04-08T12:08:20.289Z",
    "updated_at": "2024-04-08T12:08:20.289Z",
    "meta": {},
    "liveMode": true
  }
}

NOTE ON THE REDIRECT_URL FIELD

The customer will be redirected to the redirect URL after a successful or failed attempt, the URL includes the reference that was passed when initializing the widget and status and reason in case of failure.

👍 Success

${redirect_url}?reference="reference"&status="successful"

🚧 Failure

${redirect_url}?reference="reference"&status="failed"&reason="widget_closed"

Step 2: Customer authorizes payment

Once the payment initiation has been created, the payment request needs to be presented to the consumer in order to allow them to select their bank and authorize the payment. If the account id of a customer who is already linked to Mono connect is already present in the initiate endpoint above, they will be presented with an authorisation screen to input their OTP, token, pin etc immediately after the screen loads without them having to select bank and log in again.

Step 3: Track payment status

There are two ways this can be achieved.

a. Mono automatically sends a live direct_debit.payment_successful event of a transaction, to the webhook URL added to your app on the Mono Dashboard. The payload of this webhook contains the Customer's Account ID, transaction amount, transaction time, reference, transaction status etc.

b. With our Verify payment status API, you can trigger manually the status of a particular transaction via the reference which you've initially set on the Initiate endpoint. Once called, we provide all necessary payment information pertaining to a transaction as already highlighted in a. above.

NOTE

1. No webhook event will be sent until the payment process is completed end-to-end be it a successful or a failed transaction.
2. If the transaction process is not completed end-to-end, the verify endpoint will return a 404 message
3. Any payment that isn’t failed or successful returns the error below:

Request

Copy

123456

{
    "status": "failed",
    "message": "Invalid reference, payment not found",
    "timestamp": "2024-05-03T10:15:14.570Z",
    "data": null
}

Returning Users Account ID

The Account ID field which can be found in the body params of our Initiate Payment API is what enables payments for returning users. Once the Account ID of an already connected account from Mono Connect is provided on the Payment Initiation API (via account), your users or customers wouldn’t need to sign into the DirectPay Widget.

All that would be required of them would be to authorise the payment with their PIN, password or token on the payment widget. With this, the process of collecting payment from your customer's bank account is done with ease.

The following steps explain how this can be achieved:

1. Onboard your customers via Mono Connect.
2. Initiate payments via Customer's Account ID.

1. Onboard your customers via Mono Connect.

To set up payment for returning users, it is important to firstly set up Mono connect on your end. The guide here gives a comprehensive step-by-step process on how to integrate Mono Connect so that you can get your customer's account ID.

2. Initiate payments via Customer's Account ID.

With step 1 out of the way, you can proceed to initiate payment with our Initiate a Payment API. In this step, you get to pass your account id as received above to the body request, alongside other info like amount, type, description, reference etc

With the payment link now generated, you can await and confirm payment from your Customer as they would be automatically signed in the payment widget while we await for them to authorise. Tracking and verifying payments can still be achieved as explained in steps 2 and 3 at the top.

Payment Institution Redirection

When initiating a payment through Directpay and having prior knowledge of the user's bank details, you can include an institution object in the Payment Initiation API request. This object includes:

• id: This field expects the user's institution ID, obtainable from our bank listing endpoint here.

• auth_method: Here, specify the authentication method of the institution, such as mobile_banking or internet_banking.

• account_number: For institutions like GTB, provide the account number method when utilizing the pay with account number (PWA) option on the widget.

Note: When providing the institution object, the auth_method field is optional.

Upon calling the Payment Initiation API with the institution object included in the payload, a URL is generated. Users can use this URL to complete the payment. Opening the URL displays the login page for the preconfigured institution.

API request

curl --request POST \
     --url https://api.withmono.com/v2/payments/initiate \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'mono-sec-key: test_sk_from_your_dashboard' \
     --data '
{
    "amount": 20000,
    "type": "onetime-debit",
    "description": "testing",
    "reference": "ref-00001-00000001",
    "redirect_url": "https://mono.co",
    "institution": {
        "id": "5f2d08bf60b92e2888287704",
        "auth_method": "internet_banking"
    },
    "customer": {
		"name": "Samuel Olamide",
        "email": "samuel@neem.co"
    }
}
'