Effortless integrations
Integrating with Ozow is simple! Check out the guides below to see the different integration methods. They’re listed from the easiest at the top, to the most difficult at the bottom.
Effortless integrations
Integrating with Ozow is simple! Check out the guides below to see the different integration methods. They’re listed from the easiest at the top, to the most difficult at the bottom.
With this integration, you get full access to the Ozow portal, where you can easily and quickly create and send payment links to your customers. To generate a payment request, enter these details:
- the payment amount,
- customer’s name,
- reference you expect on your bank statement (e.g. an invoice number),
- and the payment link delivery method.
You can choose one of three different ways to send the payment link:
SMS: Ask for your customer’s cellphone number, and enter it into the payment request portal. Your customer will then receive an SMS with a payment link.
Email: Ask for your customer’s email address, and enter it into the payment request portal. Your customer will receive an email with a payment link.
QR Code: You’ll get a unique Ozow QR code. Your customers can then scan this QR code with their device, and then be redirected to the payment process. You also have the option to create bulk payment request links. Bear in mind, this means that you will have to send the links out (Ozow only generates bulk payment links, we don’t distribute them). That being said, we also give you the option to make static or dynamic payment requests, and give you the power to specify the payment amount and/or bank reference. For this integration, you won’t need a website, coding skills or access to developers.
This integration method is a normal HTML form with text fields that are posted to Ozow. Your customer is redirected from your website to Ozow’s payment page – from there, they’ll go through the payment process. Once their payment is successful, Ozow redirects your customer back to your website, as set out by the callback URLs in the form’s post fields. Please note that there are a few optional fields that you can use, which you can find out more about by contacting support@ozow.com.
Through this integration, you'll need a few things, such as a website and a web developer with some knowledge of server-side scripting. To make sure the data you post is 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, so a small backend server is also needed.
This integration method helps alleviate the need to redirect your customer. All you have to do is add a script file to your website. This will pull one of two simple payment screen types into your website:
1. iFrame: through iFrame, you'll have a degree of control over styling the payment screen. But it’s worth noting that iFrame is not compatible with all devices.
2. Modal: through Modal, you'll have pretty much 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, you'll need a website and a web developer with some knowledge of front-end scripting. To make sure the data being posted is 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 you need to do to set this up is call Ozow’s API, pass through a few data fields stipulating payment details, and identify yourself as the merchant.
Authorisation header fields need to be passed through to authenticate that you are, in fact, who you claim to be. To make sure data being passed remains secure, a hash needs to be generated, on the fly and posted through with the fields being sent through to Ozow’s API endpoint. We’ll then 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. You can then send the payment link to your customers in any of these 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. or a link sent via SMS, email, USSD, in-app, etc. Take note that you'll be responsible for delivering and displaying the payment link. Aside from this, you’ll also need a back-end server, as well as a proficient back-end developer with front-end web skills.
API integrations
For all the developers out there:
Step 1 - Post from Merchant Website
When your customer has made their purchase and selected Ozow as their payment method, you’ll need to post the following variables to https://pay.ozow.com.
Post variables
Generate the 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 the merchant details
section of your admin site.
3. Convert the concatenated string to lowercase.
4. Generate a SHA512 hash of the lowercase concatenated string.
Step 2 - Process Ozow response
Ozow will send the following two posts back to you:
- Redirect Response
- Notification Response
Redirect Response
Depending on where in the payment process they are, we’ll redirect your customer to the applicable page with the response variables. Please note that if the applicable URL wasn’t sent in the post variables or set for your site in your admin site, your customer won’t be redirected back to your site along with the response variables.
The URL that is used is determined as follows:
- Error URL: an error occurred during the payment process and payment was not successful.
- Cancelled URL: the user chose 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). We 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 your site in your admin site, we won't 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.
Post variables
Response 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 the merchant details section of your admin site.
3. Convert the concatenated string to lowercase.
4. Generate a SHA512 hash of the lowercase concatenated string.
Compare generated hash to the Hash value in the response variables.
Step 3 - Check transaction status using API
This step is optional, but we highly recommend it – it helps ensure that the received responses reflect the correct transaction status. This will remove any chance of anyone spoofing the Ozow response to update a transaction status on your site. Each API call needs an http header value with the your API Key.
There are two API methods you can use to check the transaction status:
- Get transaction by reference
- Get transaction
Get transaction by reference
https://api.ozow.com/GetTransactionByReference?siteCode={siteCode}&transactionReference={transactionReference}
Call this method when you want to query transactions using your reference. This method can return multiple results as Ozow doesn’t stop you from sending duplicate merchant references. However, we advise that a unique reference is sent for each transaction. The number of results returned is limited to 10.
Parameters
A successful call will return an array of the transaction object, which is described further down.
Get transaction
https://api.ozow.com/GetTransaction?siteCode={siteCode}&transactionId={transactionId}
Call this method when you want to query transactions using Ozow’s reference.
A successful call will return an array of the transaction object, which is described further down.
Transaction object
This is the object referred to in the response of the 2 API calls above.
Step 1 - Post from Merchant Website
When your customer has made their purchase and selected Ozow as their payment method, you’ll need to post the following variables to https://pay.ozow.com.
Post variables
Generate the 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 the merchant details section of your admin site.
3. Convert the concatenated string to lowercase. 4. Generate a SHA512 hash of the lowercase concatenated string.
Step 2 - Process Ozow response
Ozow will send the following two posts back to you:
- Redirect Response
- Notification Response
Redirect Response
Depending on where in the payment process they are, we’ll redirect your customer to the applicable page with the response variables. Please note that if the applicable URL wasn’t sent in the post variables or set for your site in your admin site, your customerwon’t be redirected back to your site along with the response variables.
The URL that is used is determined as follows:
- Error URL: an error occurred during the payment process and payment was not successful.
- Cancelled URL: the user chose 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). We 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 your site in your admin site, we won't 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.
Post variables
Response 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 the merchant details section of your admin site.
3. Convert the concatenated string to lowercase. 4. Generate a SHA512 hash of the lowercase concatenated string.
Compare generated hash to the Hash value in the response variables.
Step 3 - Check transaction status using API
This step is optional, but we highly recommend it – it helps ensure that the received responses reflect the correct transaction status. This will remove any chance of anyone spoofing the Ozow response to update a transaction status on your site. Each API call needs an http header value with the your API Key.
There are two API methods you can use to check the transaction status:
- Get transaction by reference
- Get transaction
Get transaction by reference
https://api.ozow.com/GetTransactionByReference?siteCode={siteCode}&transactionReference={transactionReference}
Call this method when you want to query transactions using your reference. This method can return multiple results as Ozow doesn’tstop you from sending duplicate merchant references. However, we advise that a unique reference is sent for each transaction. The number of results returned is limited to 10.
Parameters
A successful call will return an array of the transaction object, which is described further down.
Get transaction
https://api.ozow.com/GetTransaction?siteCode {siteCode} &transactionId={transactionId}
Call this method when you want to query transactions using Ozow’s reference.
A successful call will return an array of the transaction object, which is described further down.
Transaction object
This is the object referred to in the response of the 2 API calls above.