CardPaymentDoc - OSOFTPAY DEVELOPER

CONSUMING OSOFTPAY API By Credit/Debit Cards

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 https://developer.osoftpay.net 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

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 (

).

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) { } } } }

Where

1) Hash = MerchantNumber+TransactionReference+TransactionType+Amount+SiteRedirectURL

2) url = "https://developer.osoftpay.net/api/TestPublicPayments?TransactionNumber=" + 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