Documentation

Documentation2019-05-16T18:35:17+01:00

Other Useful Links

Create Account
Mobile Money Menu

API Documentation

Introduction

This document describes how a third party will connect to a MobilePayment© Interface from QoS-IC. Note that all data formats and response definitions are in conformance with the REST standard.

Design

A MobilePayment© transaction provides Mobile Money capability application programming interfaces (APIs) for third-party applications (App for short) to connect to it and use its Mobile Money capability for Bill Payment, Depositing Money in Subscribers account & Querying Subscriber’s account in a third-party system.
The subsequent sections show the message structure for Mobile Payment

RequestPayment

The RequestPayment is a request to debit mobile money from subscribers account.
Partners must code the App based on the API field requirements so that the App can send correct requests accordingly.

RequestPayment Request

The following describes the important element required to be sent for RequestPayment request.

[table id=1 /]

Sample Request

POST {context}/QosicBridge/user/requestpayment
Content-Type: application/json[Basic Authentication headers]…
{
“msisdn”: “22967307747”,
“amount”: “2000”,
“firstname”:”David”,
“lastname”:”Ashaolu”,
“transref” :”12345″,
“clientid”: “QOS3P001”
}

RequestPayment Response

The following describes the important data element required for a PaymentRequest Response.

[table id=2 /]

Successful Response:

HTTP Status Code: 202
{
“responsecode”: “01”,
“responsemsg”: “PENDING”,
“transref”: “12345”,
“comment”: null
}

Un-Successful Response (Failed authentication):

HTTP Status Code: 401
HTTP Status 401: Bad credentials

Un-Successful Response:

HTTP Status Code: 404
{
“responsecode”: “-2”,
“responsemsg”: “Invalid Client Id”,
“transref”: “12345”,
“comment”: null
}

Get Transaction Status

A Get Transaction Status message is a request to get the details of an already processed transaction.

Get Transaction Status Request

The following describes the important element required to be sent for Get Transaction Status
request.

[table id=3 /]

Sample Request

POST {context}/QosicBridge/user/gettransactionstatus
Content-Type: application/json[Basic Authentication headers]…
{
“transref” :”12345″,
“clientid”: “QOS3P001”
}

Get Transaction Status Response

The following describes the important data element required for a Transaction Status Response.

[table id=4 /]

Successful Response:

HTTP Status Code: 200
{
“responsecode”: “00”,
“responsemsg”: “SUCCESSFUL”,
“transref”: “12345”,
“comment”: “TRANSACTION APPROVED AND PROCESSED SUCCESSFULLY”
}

Un-Successful Response (Failed authentication):

HTTP Status Code: 401
HTTP Status 401: Bad credentials

Un-Successful Response:

HTTP Status Code: 404
{
“responsecode”: “-2”,
“responsemsg”: “INVALID CLIENT ID”,
“transref”: “12345”,
“comment”: “CLIENT ID DOES NOT EXIST”
}

Refund

The Refund is a request to reverse mobile money back to the Subscriber’s mobile money account. Partners must code the App based on the API field requirements so that the App can send correct requests accordingly.

Refund Request

The following describes the important element required to be sent for Refund request.

[table id=7 /]

Sample Request

POST {context}/QosicBridge/user/refund
Content-Type: application/json[Basic Authentication headers]…
{
“transref” :”56789″,
“clientid”: “QOS3P001”
}

Refund Response

The following describes the important data element required for a Refund Response.

[table id=8 /]

Successful Response:

HTTP Status Code: 200
{
“responsecode”: “00”,
“responsemsg”: “OPERATION SUCCESSFUL”,
“transref”: “56789”,
“comment”: null
}

Un-Successful Response (Failed authentication):

HTTP Status Code: 401
HTTP Status 401: Bad credentials

Un-Successful Response:

HTTP Status Code: 404
{
“responsecode”: “-2”,
“responsemsg”: “Invalid Client Id”,
“transref”: “56789”,
“comment”: null
}

Communication

Requests will be sent over the REST protocol.

Security

Requests will be sent over HTTPS only. Each request is also sent using a Basic Authentication. With Basic Authentication, clients send its Base64 encoded credentials with each request, using HTTP [Authorization] header. That means each request is independent of other request and server may/does not maintain any state information for the client.

Response Code

Please refer to the standard HTTP response codes. Where anything starting with 2XX signifies approved, 4XX means client error and 5XX indicates server error. See Appendix A for response code descriptions.

APPENDIX A

Sample response Codes obtainable are below. Note that this list is not exhaustive.

[table id=9 /]