Partners API (Directpay)

Overview

To integrate the Partners' API for DirectPay into your current software solution, you will need to:

1. Fetch all DirectPay Financial Institutions.

The first step to implementing Mono DirectPay (WhiteLabel) is to get the list of all the supported financial institutions for DirectPay. Here’s how to do this.

Make a Get request to the endpoint

https://api.withmono.com/v1/institutions

Response

[
	{
		"_id": "5f2d08be60b92e2888287702",
		"name": "GTBank",
		"type": "PERSONAL_BANKING",
		"auth_methods": [
				{
				"type": "internet_banking",
				"name": "Internet Banking",
				"ui": {
				"title": "Log in to GTBank",
				"form": [
						{
						"type": "elements.input",
						"name": "username",
						"hint": "UserID or Account Number",
						"contentType": "string"
						},
						{
						"type": "elements.input",
						"name": "password",
						"hint": "Password",
						"contentType": "password"
						}
				  ]
				},
			"_id": "60d071acf73e6468062ae8de"
		}
	],
	"icon": "https://mono-public-bucket.s3.eu-west-2.amazonaws.com/images/gtbank-icon.png",
	"identifier": "mono.connections.gtbank",
	"primaryColor": "#E24407",
	"country": "ng",
	"ui": {
	"title": "Log in to GTBank",
	"form": [
			{
			"type": "elements.input",
			"name": "username",
			"hint": "UserID or Account Number",
			"contentType": "string"
			},
			{
			"type": "elements.input",
			"name": "password",
			"hint": "Password",
			"contentType": "password"
			}
		]
	}
},

From the response above, _id refers to the institution ID, while the auth_methods array contains the different authentication method types and the UI object available for a financial institution. These two parameters, alongside your App ID (which you can find on the Apps page of your dashboard), will be used in the next step to create a Mono-Connect session.

2. Create mono-connect session.

The next step is to create a Mono-Connect session by making a POST request to the endpoint below with the institution ID, auth_method, and App ID. Make sure that you pass your mono-sec-key (you can retrieve your secret key on your Mono dashboard) in the headers for a successful request to be made.

Endpoint

https://api.withmono.com/v1/connect/session

Body Parameters

{
	"app": "61e96db488900076f46fka2",
	"institution": "5f2d08be60b92e2888287702",
	"auth_method": "internet_banking"
}

Response

{
	"id": "session_qfa6PH7bBH",
	"app": "61fd1e96db488bb09f46f1a2",
	"institution": "5f2d08be60b92e2888287702",
	"auth_method": "internet_banking",
	"expiresAt": 1648193002017,
	"ui": {
	"title": "Log in to GTBank",
	"form": [
			{
			"type": "elements.input",
			"name": "username",
			"hint": "UserID or Account Number",
			"contentType": "string"
			},
			{
			"type": "elements.input",
			"name": "password",
			"hint": "Password",
			"contentType": "password"
			}
		]
	}
}

3. Login user to Financial institution

To log in, you need to get the x-session-id returned from the response above in step two and pass it in the headers along with the mono-sec-key. Then, make a POST request to the login endpoint with the user’s credentials.

Endpoint

https://api.withmono.com/v1/connect/login

Body Parameters

{
	"username": "user_good",
	"password": "123456"
}

Response

// Successfully logged in.
{
	"status": 200,
	"responseCode": 99,
	"data": {
		"code": "code_euTJM7yOuohSpSFVoBtc"
		}
}
// Requires user input to select the account. [200]
{
	"status": 200,
	"responseCode": 101,
	"data": [
		{
		"accountNumber": "0001557338",
		"name": "NAME ON ACCOUNT",
		"type": "CURRENT_ACCOUNT",
		"currency": "NGN",
		"status": "active",
		"balance": 14457
		},
		...accounts
	]
}

// Requires an answer to a Security question
{
	"status": 200,
	"responseCode": 102,
	"data": {
	"title": "Kindly Answer Your Security Question",
	"form": [
			{
			"type": "elements.input",
			"name": "answer",
			"hint": "Which city were you born in ?",
			"contentType": "string"
			}
		]
	}
}

It is important to note that an institution might need multiple levels of authorization flow before granting user access. For this reason, the next steps for the authorization flow are determined by the response code received from the login response above.
If the status returned is 200, you will obtain a response code of either 99, 101, or 102.
'99' indicates that the user has successfully signed in. You may now proceed to create a payment session.
'101' indicates that your user has several accounts. The user would be required to pick the desired account to be enrolled. An array containing all of the discovered accounts will be returned in the response.
'102' indicates that an input is required from the user to proceed, this may be a security question, OTP, token, etc.

Re-commit session again if required
At this point, if the response code received is either 101 or 102, a user’s input is required during the process (e.g account selection, OTP, security answer).

Also, before you make a POST request to the endpoint, ensure you pass the x-session-id and mono-sec-key in the headers.

Endpoint

https://api.withmono.com/v1/connect/commit

Body Parameters

{
 "account": ""  //index of selected account
 "answer": "" 
 "otp":""
}

The body parameter could be either one of the following (account, answer, OTP) depending on the response code received after a successful login attempt.

Response

{
  "status": 200,
  "responseCode": 99,
  "data": {
    "code": "code_q1i8VHYoAnZo5OZEBkmK"
  }
}

Once the code has been retrieved in the authorization flow, proceed to Create a DirectPay session

4. Create DirectPay Session.

After successful login, the next step is to create a payment session by making a POST request to the endpoint with the required body parameters.

Now, ensure you pass the mono-sec-key and x-session-id in the headers for a successful request to be made.

Endpoint

https://api.withmono.com/v1/direct-pay/session

Body Parameters

{
	"amount": "", //in kobo
	"type": "", // onetime-debit or recurring-debit
	"description":"", // E.g Shipping fee
	"reference":"" // Unique reference (Minimum of 10 characters)
}

Response

{
	"status": 200,
	"responseCode": 102,
	"data": {
			"session": {
			"id": "kY0Eu5Y3aW",
			"type": "onetime-debit",
			"amount": 213,
			"description": "Payment for shoes",
			"reference": "000000000000003"
			},
	"ui": {
			"title": "Please Note: GTBank requires a hardware token to set up a direct debit with Apara.\\nEnter your generated token code:",
			"form": [
					{
						"type": "elements.input",
						"name": "answer",
						"hint": "Please enter the security answer",
						"contentType": "password"
					},
					{
						"type": "elements.input",
						"name": "token",
						"hint": "Please enter token",
						"contentType": "password",
						"length": 6
					}
			]
		}
	}
}

5. Create charge on user's account.

The next step is to create a charge by making a POST request to the endpoint. To ensure that a successful request is made, you have to pass the mono-sec-key and x-session-id in the headers.

Endpoint

https://api.withmono.com/v1/direct-pay/charge

Body Parameters

// No body param is required here, simply make the POST request without it

Response

{
  "status": 200,
  "responseCode": 102,
  "data": {
    "invoice": {
      "account": {
        "name": "Samuel Olamide",
        "accountNumber": "0131883461",
        "institution": {
          "name": "GTBank",
          "bank_code": "058",
          "icon": "https://mono-public-bucket.s3.eu-west-2.amazonaws.com/images/gtbank-icon.png"
        }
      },
      "type": "onetime-debit",
      "reference": "000000000000003",
      "description": "Payment for shoes",
      "amount": 213,
      "currency": "NGN"
    },
    "ui": {
      "title": "For security purposes, please generate a token and enter it below to complete this transaction.",
      "form": [
        {
          "type": "elements.input",
          "name": "token",
          "hint": "Please enter token",
          "contentType": "password",
          "length": 6
        }
      ]
    }
  }
}

6. Capture charge on user's account.

The final step is to capture the charge. Depending on the response gotten from the create charge endpoint above, you will require either a PIN, security answer, token, etc to make the POST request.

To make a successful POST request, you need to pass the mono-sec-key and x-session-id in the headers.

Endpoint

https://api.withmono.com/v1/direct-pay/capture

Body Parameters (could be one of the following)

{
	"answer":"",
	"token":"", // optional
	"bvn":"", // optional
	"pin":"" // optional
}

Response

{
  "type": "onetime-debit",
  "data": {
    "_id": "618cccfa8a2dcf366b8b4cea",
    "status": "successful",
    "description": "Payment for shoes",
    "amount": 21300,
    "account": "618ccced8a2dcf366b8b4bc1",
    "customer": null,
    "reference": "000000000000003",
    "created_at": "2021-11-11T07:57:46.408Z",
    "updated_at": "2021-11-11T07:58:09.708Z"
  }
}

With the above steps, we have shown how easy it is to implement Mono DirectPay White Label to your product and start accepting payments from customers securely. You can also watch this quick tutorial video on how to implement the DirectPay White Label API via Postman.

📘
NOTE

Ensure you pass in x-session-id to your headers in Steps 3 to 6.

Please use the sandbox credentials for the required appropriate methods:
Pin- 1234
Token - 123456
Answer(security) - lagos

All partners will be on testing mode for DirectPay partners API. This will be enabled for your business once the team is done with testing.