CONSUMING OSOFTPAY API By Bank Branch Deposits, USSD, etc

Just like the Credit/Debit Card Payment Integration, Consuming or connecting your web apps to the OSOFTPAY Bank Branch services is very simple. The basic way is by using REST to make an HTTP POST to get OPR(OSOFTPAY REFERENCE) details and an HTTP GET to retrieve payment status. You need to know that a reference (OPR) will be generated for you to choose where to make payment. You might decide to make payment at any bank branch with this reference or use your phone USSD services. We have access also to QuickTeller, ATM Machines to facilitate payments for references generated through this method.


OSOFTPAY required/mandatory fields to get OPR

Note: The fields below are not all the fields available. These are the required/mandatory fields to POST OPR instructions to OSOFTPAY


Field Field Description Data Type
MerchantNumber This is a mandatory field that is provided by OSOFTPAY. It is used to identify the merchant placing the POST request. Note that the demonstration MerchantNumber can be obtained when you login to https://developer.osoftpay.net and create a Test Merchant string
ServiceUrl This is a mandatory field that you need to provide OSOFTPAY in your POST request to receive notification of your transaction. url
CustomerName This is a mandatory field that you need to provide OSOFTPAY in your POST request as the Name of the Customer. string
ProcessedBy This is a mandatory field that you need to provide OSOFTPAY in your POST request as an email address. Note that customers receives email notification on payments on this address. Therefore, make sure this is an email address. string(email)
ItemName This is a mandatory field that you need to provide OSOFTPAY in your POST request as the name of the Item you are generating OPR for. string
Amount This is a mandatory field that you need to provide OSOFTPAY in your POST request as the cost of the item. Please note that a fee of 1.5%+100 is attracted on each payment as commission. Therefore include the commission on your Item cost to get actual value of the Item cost. money

POST Instruction to get OPR
HTTP POST Sample Form
<form id="form1" action="https://developer.osoftpay.net/api/TestBranchPayments" method="post"> <input name="MerchantNumber" value="xxxxxxxxx" type="hidden" /> <input name="ServiceUrl" value="http://returnportalurl" type="hidden" /> <input name="CustomerName" value="Namexxxxx" type="hidden" /> <input name="ProcessedBy" value="emailxxxx@xxxx.com" type="hidden" /> <input name="ItemName" value="ItemNamexxx" type="hidden" /> <input name="Amount" value="5000" type="hidden" /> <input type="submit" value="Get OPR" /> </form>

Note: The fields provided in the form above are required for a successful POST instruction to get OPR on the OSOFTPAY platform. You can customize the form to receive values as inputs depending on your development platform but make sure the name property is same as used on the sample form.

In order to experience a succesful test, you need to create a merchant on the developers portal.

OPR Return Parameters
Once you have posted an instruction to get OPR from OSOFTPAY, whether the OPR is successfully generated or not, you should be expecting the following on the return url you specified in your POST form as above (
<input name="ServiceUrl" value="http://returnportalurl" type="hidden" />
).
OPR (This is the reference that is generated and sent back to you by OSOFTPAY)

Cust (This is Customer Name, Number or unique identifier you sent to OSOFTPAY)

Amount (This is the Amount to be tied to the OPR Generated)

ResDesc (This is the description of the response received from OSOFTPAY in plain english)


GET Payment Status

Once you obtain your OPR, you are expected to take it to any bank of your choice for deposit, OR you can use USSD service to Make Payment OR use the QuickTeller to make Payment.

Here is a typical ASP.NET C# sample using HttpClient:

using (HttpClient client = new HttpClient()) { ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); using (HttpResponseMessage response = client.GetAsync(url).Result) { using (HttpContent content = response.Content) { var json = content.ReadAsStringAsync().Result; APIBRANCHRESPONSE result = JsonConvert.DeserializeObject<APIBRANCHRESPONSE> (json); if (result != null) { } } } }
Where
1)url= "https://developer.osoftpay.net/api/TestBranchPayments?OPR=" + OPR + "&Cust=" + Customer + "&Amount=" + Amount

2) APIBRANCHRESPONSE is a response object with the following properties:
public string OPR { get; set; } public string Cust { get; set; } public string ResDesc { get; set; }


Full description of how this works

1) Place an HTTP POST call using the sample form above

2) Receive OPR from OSOFT pay on your Return URL Specified as ServiceUrl

3) Take OPR to bank and present for payment OR Use OPR on QuickTeller to make payment OR Dial the USSD code (Will be provided on GO-Live) on your phone and follow the prompt

4) After Payment, you will have to verify payment on your pprtal manually to update your database. In the V2 of this API, we will be introducing a listener for authomatic payment verification.