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:
- The payment amount
- The customer’s name
- The reference expected on merchant’s bank statement (e.g. an invoice number)
- The payment link delivery method
Delivery of the payment link can be done in one of three Ozow convenient ways:
- 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.
- 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.
- 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:
- 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.
- 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:
- A button on a webpage or pdf invoice
- A link on a webpage or pdf invoice
- A QR code on a t-shirt, website, pdf invoice, banner etc
- 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
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:
- Concatenate the post variables (excluding HashCheck) in the order they appear in the post variables table
- Append your secret key to the concatenated string. Your secret key can be found in merchant details section of the merchant admin site.
- Covert the concatenated string to lowercase.
- 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 redirect the user to the applicable page with the response variables. 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 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:
|
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:
- Concatenate the response variables (excluding Hash) in the order they appear in the post variables table.
- Append your secret key to the concatenated string. Your secret key can be found in merchant details section of the merchant admin site.
- Covert the concatenated string to lowercase.
- Generate a SHA512 hash of the lowercase concatenated string.
- 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 |