DirectPay Partners' API


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

  1. Fetch all DirectPay Financial Institutions.
  2. Create mono-connect session.
  3. Login user to DirectPay Financial institution.
  4. Understand next steps for the returned response.
  5. Re-commit session again if required.
  6. Create DirectPay Session.
  7. Create charge on user's account.
  8. Capture charge on user's account.

1. Fetch all DirectPay Financial Institutions.

With the List DirectPay Institutions API, all supported institutions will be returned. Each returned institution object contains the institution ID, the name, the type, and a UI object which you may want to render on your frontend, as it contains an appropriate title and the input name fields that pertains to these institutions. These input name fields are very important because it would help as it would help in creating key-value fields when logging in to the Login to Institution endpoint.
Also, it is recommended that you cache the results returned for optimal loading performance from your end.

2. Create mono-connect session.

After fetching the available institutions as done above, you will need to make a request to the Create Session endpoint. What will be required are the authentication method as returned in the institution endpoint, the institution ID itself and an App ID which you can find on the Apps page section on your dashboard. If this request is successful, we return a JSON response that contains a session id, the app id, institution id, the expiry time of this session and a U.I object which you can render on your frontend with a title and the names of the login input fields.

3. Login user to Financial institution

Use the returned session token above to login to the desired financial institution by the user to the Login to Institution API alongside their login credentials.

4. Understand next steps for the returned response

The next steps for the authorization flow are determined from the response code received from the login response. Based on the step above, as long as the status returned is 200, you will receive a response code which will either be 99, 101, 102.
99- This means that your user has logged in successfully. You can proceed to step 6 to create a DirectPay session

101- This means that your User has multiple accounts. We would require the user to select the desired account that will be enrolled. An array that contains all the found accounts will be returned also on the data parameter.

102- This means that an input is required from the user to proceed (security question/otp/token etc)

5. Re-commit session again if required

At this moment, if the response code received is either be 101 or 102:

101- You will need to get the index of the account selected by the user, then pass that index to the Commit Session endpoint in the body of the request as this:

  "account": "index of selected account"

102- You will need to pass the security answer/OTP to the Commit Session endpoint in the body of the request as this:

  "answer": "my security answer"


In case a session does not need to be committed and a commit request is made. the server will respond with 400 Bad Request response.

    "status": 400,
    "message": "Invalid operation or the operation isn't allowed yet."

6. Create DirectPay Session.

With the DirectPay Session API, you initiate a DirectPay request session with an amount, type, description and reference in your body.

7. Create charge on user's account.

Here, you create a charge with an empty body, to get the required form authorisation method e.g "name": "pin" in the form object via the Create Charge API.

8. Capture charge on user's account.

In this final step, you Capture a charge by passing in the authorisation method which we have in step 7 to be for instance a pin with the Capture charge API. (Depending on step 7, the auth. method could be a security answer, token or otp etc)



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

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

  3. 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.

Did this page help you?