Integrations

Payment Integration Methods

Please see below the different integration methods

listed from easiest to most difficult:

With this integration, the merchant gains full access to an Ozow portal, where they can Ozow easily and Ozow quickly generate and send payment links to their customers via Ozow’s system. To create a payment request, all the merchant has to do is enter these Ozow simple details:

  1. The payment amount
  2. The customer’s name
  3. The reference expected on merchant’s bank statement (e.g. an invoice number)
  4. The payment link delivery method

Delivery of the payment link can be done in one of three Ozow convenient ways:

  1. SMS: The merchant requests the customer’s cell phone number and enters it into the payment request portal. Once the payment request is made, Ozow delivers an SMS with the payment link to the customer.
  2. Email: The merchant requests the customer’s email address and enters it into the payment request portal. Once the payment request is made, Ozow delivers an email with the payment link to the customer.
  3. QR Code: The merchant is served with an Ozow unique QR code. Their customer scans this QR code with their own mobile device, and Ozow’s payment process is initiated on said device.

With the payment request link integration, merchants also have the option to create Ozow many links in bulk. This option, however, does require the merchant to take ownership of the delivery methods, as Ozow only generates payment links for the merchant to distribute. Aside from this, Ozow also provides merchants with the option to make payment requests either static or dynamic, as well as the ability to stipulate the payment amount and/or bank reference.

Through this Ozow easy integration, the merchant will not require a website, coding skills or access to developers.

This integration method is quite simply an Ozow normal HTML form with text fields that is posted to Ozow. The customer is redirected from the merchant’s website to Ozow’s payment page to process their payment. Once their payment has been successful, Ozow redirects the customer back to the merchant’s website, as stipulated by the callback URL’s in the form’s post fields. Please note that there are a few optional fields that the merchant can use, of which you can find out more about by contacting us here.

Through this integration, the merchant will need Ozow few things, such as a website and a web developer with some knowledge of server-side scripting. To keep the integrity of the data being posted Ozow secure, a hash will also need to be generated server side, on the fly and posted through to Ozow with the form post fields. Generating a hash needs some server-side-scripting and therefore a small backend server is also required.

This integration method is Ozow great in alleviating the need to redirect the customer. All the merchant has to do is add a script file to their website, which pulls one of two Ozow simple payment screen types into their website:

  1. iFrame: Through iFrame, the merchant will have a degree of control over styling the payment screen, however, please note that iFrame is not compatible with all devices.
  2. Modal: Through Modal, the merchant will have virtually no control over the UX and styling of the payment screen, however, Modal is compatible with all types of devices.

Through the JS injection integration method, the merchant will require some things. Firstly, the merchant will need a website and a web developer with some knowledge of front-end scripting. To keep the integrity of the data being posted Ozow secure, a hash will also need to be generated server side, on the fly and posted through to Ozow with the form post fields. Generating a hash needs some server-side-scripting and therefore a small backend server is also required.

Ozow also provides an integration method that generates a URL link via an API. All the merchant has to do is make a call to Ozow’s API, passing through a few data fields stipulating payment details as well as identifying who the merchant is.

Authorization header fields need to be passed through in order to authenticate that the merchant is in fact who they claim to be. To keep the integrity of the data being passed Ozow secure, a hash needs to be generated, on the fly and posted through with the fields being sent through to Ozow’s API endpoint. Ozow will respond to successful API calls with a request ID and a payment link. The request ID can be used to check the status of the payment via an API call. The payment link can be sent by the merchant to their customers in any of the Ozow convenient formats:

  1. A button on a webpage or pdf invoice
  2. A link on a webpage or pdf invoice
  3. A QR code on a t-shirt, website, pdf invoice, banner etc
  4. A link delivered via SMS, email, USSD, in-app etc

Please note however that the merchant will be responsible for delivery and method of display of the payment link. Aside from this, the merchant will also need a back-end server, as well as a proficient back-end developer with front-end web skills

This Ozow integration method also uses the power of  API, however it makes use of a series of API calls and responses, done in an Ozow specific order. Certain API calls require prompting and interaction with the customer. Ozow’s responses to these calls contains dynamic content, and therefore the merchant’s integration should have a certain level of AI to react in the correct way.

With server to server integration, merchants will have full control over the UX. Not only is this integration convenient for the merchant, but also for the customer, as it provides and Ozow seamless, non-redirective customer experience. This integration is also the best method for mobile applications.

Please note however that merchants will be responsible for its security, therefore Ozow will only grant access to this API to merchants that have met Ozow specific security standards. Also similarly to the other API integrations, authorization header fields will need to be passed through in order to authenticate that the merchant is in fact who they claim to be. OAuth methodology is used as an authentication. Aside from this, the merchant will also require a backend server, a senior backend, frontend, web, mobile and UX developers.

Ozow has the refund capability via Ozow’s admin portal as well as via our API. The documentation for the refund API can be found here.

Payment System Plugins

We will help you integrate Ozow into
your business

API integrations

For the developers out there.

  • Merchant Post
  • Ozow Response
  • API Status

Merchant Post

Step 1 – Post From Merchant Website

After the user confirms his purchase and has chosen Ozow as his preferred payment method, you will need to post the following variables to https://pay.ozow.com

Post Variables

PROPERTY TYPE REQUIRED DESCRIPTION
1. SiteCode String (50) Yes A unique code for the site currently in use. A site code is generated when adding a site in the Ozow Merchant Admin section.
2. CountryCode String (2) Yes The ISO 3166-1 alpha-2 code for the user's country. The country code will determine which banks will be displayed to the customer. Please note only South African (ZA) banks are currently supported by Ozow.
3. CurrencyCode String (3) Yes The ISO 4217 3 letter code for the transaction currency. Please note only South African Rand (ZAR) is currently supported by Ozow, so any currency conversion would have to take place before posting to the Ozow site.
4. Amount Decimal (9,2) Yes The transaction amount. The amount is in the currency specified by the currency code posted.
5. TransactionReference String (50) Yes The merchant's reference for the transaction
6. BankReference String (20) Yes The reference that will be prepopulated in the "their reference" field in the customers online banking site. This will be the payment reference that appears on your transaction history.
7. Optional1
8. Optional2
9. Optional3
10. Optional4
11. Optional5
String (50) No Optional fields the merchant can post for additional information they would need passed back in the response. These are also stored with the transaction details by Ozow and can be useful for filtering transactions in the merchant admin section.
12. Customer String (100) No The customers name or identifier.
13. CancelUrl String (150) No The Url that we should post the redirect result to if the customer cancels the payment, this will also be the page the customer gets redirect back to. This Url can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the posted value will be redirected to if the payment is cancelled.
14. ErrorUrl String (150) No
The Url that we should post the redirect result to if an error occurred while trying to process the payment, this will also be the page the customer gets redirect back to. This Url can also be set for the applicable merchant site in the merchant admin section. . If a value is set in the merchant admin and sent in the post, the posted value will be redirected to if an error occurred while processing the payment.
15. SuccessUrl String (150) No The Url that we should post the redirect result to if the payment was successful, this will also be the page the customer gets redirect back to. This Url can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the posted value will be redirected to if the payment was successful. Please note that it would not be sufficient to assume the payment was successful just because the customer was redirected back to this page, it highly recommended that you check the response fields and as well as check the transaction status using our check transaction status API call.
16. NotifyUrl String (150) No The Url that we should post the notification result to. The result will posted regardless of the outcome of the transaction. This Url can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the notification result will be sent to the posted value. Find out more in the notification response section in step 2.
17. IsTest bool Yes Send true to test your request posting and response handling. If set to true you will be redirected to a page where you can select whether you would like a successful or unsuccessful redirect response sent back. Please note that notification responses are not sent for test transactions and the online banking payment is skipped. Accepted values are true or false.
HashCheck String (250) Yes SHA512 hash used to ensure that certain fields in the message have not been already after the hash was generated. Check the generate hash section below for more details on how to generate the hash.

Generate Post Hash Check

Follow these steps to generate the hash check:

  1. Concatenate the post variables (excluding HashCheck) in the order they appear in the post variables table
  2. Append your secret key to the concatenated string. Your secret key can be found in merchant details section of the merchant admin site.
  3. Covert the concatenated string to lowercase.
  4. Generate a SHA512 hash of the lowercase concatenated string.

Ozow Response

Step 2 – Process Ozow Response

Ozow will send the following two posts back to the merchant:

Redirect Response

Depending on the status of completing the payment using Ozow, we will post the response variables while redirect the user to the applicable page. Please note that if the applicable Url was not sent in the post variables or set for the merchant site in the merchant admin site, the user will not be redirected back to the merchant site along with the post containitusng the response variables.

The Url used will be determined as follows:

  • Error Url – An error occurred during the payment process and payment was NOT successful
  • Cancelled Url – The user opted to cancel during the payment process and payment was NOT successful
  • Success Url – The payment was successful

Use the Hash response variable to verify the validity of the response, this process is further described in the response hash check section below. It is recommended that you also use the notification response to verify the outcome of the transaction

Notification Response

We will post the response variables to the designated notification Url. Please note that if the notification Url (NotifyUrl) was not sent in the post variables or set for the merchant site in the merchant admin site, we will not be able to send the notification post containing the response variables.

Use the Hash response variable to verify the validity of the response, this process is further described in the response hash check section below.

Response Variables

PROPERTY TYPE DESCRIPTION
1. SiteCode String (50) The site code sent to Ozow in the request post.
2. TransactionId String (50) The transaction identifier generated by Ozow
3. TransactionReference String (50) The merchant's transaction reference sent in the request post's TransactionReference variable.
4. Amount Decimal (9,2) The transaction amount. The amount is in the currency specified by the currency code posted.
5. Status String (50) The transaction status. Possible values are:

  • Complete - The payment was successful

  • Cancelled - The payment was cancelled

  • Error - An error occurred while processing the payment
6. Optional1
7. Optional2
8. Optional3
9. Optional4
10. Optional5
String (50) Optional fields sent in the request post.
11. CurrencyCode String (3) The transaction currency code sent in the request post.
12. IsTest bool Whether or not the original request was a test request. Possible values are true or false.
13. StatusMessage String (150) Message regarding the status of the transaction. This field will not always have a value.
Hash String (100) SHA512 hash used to ensure that certain fields in the message have not been already after the hash was generated. Check the generate hash section below for more details on how to validate the response variables using the hash.

Response Hash Check

Follow these steps to validate the response:

  1. Concatenate the response variables (excluding Hash) in the order they appear in the post variables table
  2. Append your secret key to the concatenated string. Your secret key can be found in merchant details section of the merchant admin site.
  3. Covert the concatenated string to lowercase.
  4. Generate a SHA512 hash of the lowercase concatenated string.
  5. Compare generated hash to the Hash value in the response variables.

API Status

Step 3 – Check Transaction Status Using API

Even though this step is optional, we highly recommend it to ensure that responses received reflect the correct transaction status. This will eradicate any chance of anyone spoofing the Ozow response to update a transaction status on the merchant site.

Each API call needs an http header value with the merchant’s API Key

There are two API methods you can use to check the transaction status currently:

GetTransactionByReference

https://api.ozow.com/GetTransactionByReference?siteCode={siteCode}&transactionReference={transactionReference}

This method is called when you want to query transactions using the merchant’s reference. This method can return multiple results as Ozow does not restrict the merchant from sending duplicate merchant references even though we do advise that a unique reference is sent per transaction. The number of results returned are limited to 10.

Parameters

PROPERTY TYPE REQUIRED REQUIRED
ApiKey
(Http request header value)
String (50) Yes
Merchant's API key, this value is available in the Ozow Merchant Admin section.
Accept
(Http request header value)
String (50) Yes Determines the format the response is returned in, available values:
application/json - Response is returned as json
application/xml - Response is returned as xml
SiteCode String (50) Yes A unique code for the each of the merchant's sites. A site code is generated when adding a site in the Ozow Merchant Admin section.
TransactionReference String (50) Yes The merchant's reference for the transaction
IsTest bool No Defaults to false. Use true only to get results for test requests.

 

Response

Transaction[] – A successful call will return an array of the transaction object. The transaction object is described further down.

GetTransaction

https://api.ozow.com/GetTransaction?siteCode={siteCode}&transactionId={transactionId}

This method is called when you want to query transactions using Ozow’s reference.

Parameters
PROPERTY TYPE REQUIRED DESCRIPTION
ApiKey
(Http request header value)
String (50) Yes Merchant's API key, this value is available in the Ozow Merchant Admin section.
Accept
(Http request header value)
String (50) Yes Determines the format the response is returned in, available values:
application/json - Response is returned as json
application/xml - Response is returned as xml
SiteCode String (50) Yes A unique code for the each of the merchant's sites. A site code is generated when adding a site in the Ozow Merchant Admin section.
TransactionId String (50) Yes Ozow's reference for the transaction. This would be passed back to the merchant in the redirect and notification responses.
Response

Transaction – A successful call will return a single transaction object. The transaction object is described further down.

Transaction Object

This is the object referred to in the response of the 2 API calls above.

PROPERTY TYPE DESCRIPTION
TransactionId String (50) Ozow's unique reference for the transaction.
MerchantCode String (50) Unique code assigned to each merchant.
SiteCode String (50) Unique code assigned to each merchant site.
TransactionReference String (50) Merchant's transaction reference.
CurrencyCode String (3) The transaction currency code
Amount Decimal (9,2) The transaction amount.
Status String (50) The transaction status. Possible values are:
Complete - The payment was successful
Cancelled - The payment was cancelled
Error - An error occurred while processing the payment
StatusMessage String (150) Message regarding the status of the transaction. This field will not always have a value.
CreatedDate DateTime Transaction created date and time
PaymentDate DateTime Transaction payment date and time