Consuming or connecting your web apps to the OSOFTPAY services is very simple. The basic way is by using REST to make an HTTP POST to send payment details and an HTTP GET to retrieve payment status. We also make use of SHA12 cryptography to hash request details.

OSOFTPAY required/mandatory fields to POST payments

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

Field Field Description Data Type
TransactionType This is a mandatory field that distinguishes your transaction on the OSOFTPAY. The default value is "2" numeric
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 and create a Test Merchant string
SiteRedirectURL This is a mandatory field that you need to provide OSOFTPAY in your POST request to receive notification of your transaction. url
TransactionReference This is a mandatory field that you need to provide OSOFTPAY in your POST request as a unique transaction number. Note that this is what you use to request for or query any transaction from the OSOFTPAY through HTTP GET Request. string
CustomerName This is a mandatory field that you need to provide OSOFTPAY in your POST request as the Name of the Customer. string
CustomerId 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)
PaymentItemName This is a mandatory field that you need to provide OSOFTPAY in your POST request as the name of the Item you are processing payment 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
Hash This is a mandatory field that you need to provide OSOFTPAY in your POST request. This is done using SHA12 cryptography combining MerchantNumber+TransactionReference+TransactionType+Amount+SiteRedirectURL string

POST Payment

Hash Calculations:
Hash is computed using MerchantNumber+TransactionReference+TransactionType+Amount+SiteRedirectURL and then executed using SHA12 Algorithm

HTTP POST Sample Form
<form id="form1" action="" method="post"> <input name="TransactionType" value="2" type="hidden" /> <input name="MerchantNumber" value="xxxxxxxxx" type="hidden" /> <input name="SiteRedirectURL" value="http://returnportalurl" type="hidden" /> <input name="TransactionReference" value="Refxxxxx" type="hidden" /> <input name="CustomerName" value="Namexxxxx" type="hidden" /> <input name="CustomerId" value="" type="hidden" /> <input name="PaymentItemName" value="ItemNamexxx" type="hidden" /> <input name="Amount" value="5000" type="hidden" /> <input name="Hash" value="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" type="hidden" /> <input type="submit" value="Pay via OSOFTPAY" /> </form>

Note: The fields provided in the form above are required for a successful POST Payment 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, copy the merchant number and the test service name, then use it to perform your test. For example, the default PaymentItemName to use is "TestServiceName1". That is, on the Sample form above, the value of PaymentItemName is value="TestServiceName1".

Payment Return Parameters
Once you have posted a payment to OSOFTPAY, whether the payment is successful or not, you should be expecting the following on the return url you specified in your POST form as above (
<input name="SiteRedirectURL" value="http://returnportalurl" type="hidden" />
TransactionReference (This is the reference you submitted to OSOFTPAY as a unique identifier of that particular transaction)

PayRef (This is the reference sent to you by OSOFTPAY upon successful transaction. This means that if a transaction fails for any reason, the PayRef will return empty)

ResCode (This is the response code associated with the status of your transaction. Every transaction, be it successful or not has a response code)

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

GET Payment Status

Getting payment status requires that you Hash your request in the request client header and also specify the media type as "application/json".

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

using (HttpClient client = new HttpClient()) { ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; client.DefaultRequestHeaders.Add("Hash", Hash); 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; OSOFTRESPONSE result = JsonConvert.DeserializeObject<OSOFTRESPONSE> (json); if (result != null) { } } } }
1) Hash = MerchantNumber+TransactionReference+TransactionType+Amount+SiteRedirectURL

2) url = "" + TransactionNumber + "&Amount=" + Transaction_Amount

3) OSOFTRESPONSE is a response object with the following properties:
public string MerchantNumber { get; set; } public decimal ProductId { get; set; } public decimal TransactionType { get; set; } public decimal Amount { get; set; } public string Currency { get; set; } public string SiteRedirectURL { get; set; } public string TransactionReference { get; set; } public string Hash { get; set; } public decimal PaymentItemId { get; set; } public string SiteName { get; set; } public string CustomerId { get; set; } public string CustomerIdDescription { get; set; } public string CustomerName { get; set; } public string CustomerNameDescription { get; set; } public string PaymentItemName { get; set; } public string retRef { get; set; } public string PayRef { get; set; } public string ResponseCode { get; set; } public string ResponseDescription { get; set; } public DateTime TransactionDate { get; set; } public DateTime ConfirmationDate { get; set; } public string GatewayRef { get; set; } public string SwitchRef { get; set; } public string CardNumber { get; set; } public string ApprAmt { get; set; }

OSOFTPAY Split Setup

To configure split on the OSOFTPAY platform is quite easy. Locate Merchant Setting,

1) Edit and set Account Number and Bank Name on the record with description "SPLIT_ACCOUNT_DETAILS". That is, Name = Bank Name and Value = Bank Account Number

2) Edit and set Split Deduction percentage on the record with Name "SPLIT_AMOUNT". That is, Value = Split Percentage, example: 15 (to signify 15 percent)

It is worthy to note that split can only occur in two directions. The first part goes to the merchant and the other part to the "SPLIT_ACCOUNT_DETAILS" as specified. Therefore, only one split details will work

Test Card

Test card Type to be used is Verve

Test Type Card Number Card Expiry Card CCV2 Card PIN
Successful Transactions 6280511000000095 Dec 2026 123 0000
Insufficient Fund 5061030000000000027 Sept 2019 123 1234
Incorrect PIN 5061030000000000035 Sept 2019 123 0000

Sample Codes

C# Sample Code Click to Download

PHP Sample Code Click to Download


Wordpress WooCommerce Click to Download

User Acceptance Testing (UAT)

UAT Form Click to Download

Every developer needs to complete this checklisted tasks before golive

Integration Support

For integration support, Send concerns to