Other Useful Links
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.
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.
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.
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.
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.
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.
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.