Documentation

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.

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

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.

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

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”
}

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

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
}

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

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

Sample Request

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

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

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”
}

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.

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

Sample Request

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

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

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
}

Requests will be sent over the REST protocol.

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.

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.

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