Last updated: Mar 07th, 2019

Get Started

The Ozow Payment API allows you to build Ozow's real-time EFT functionality directly into your website or app. This integration method gives you more flexibility but would require more effort than using the Ozow hosted method.

Before getting started you require the following:
  • Your Ozow merchant details:
    • Site code
    • Private key
    • API key
  • Your Ozow merchant account has been granted API access

API Access

This API will only be made available to selected merchants, so make sure you apply for access before commencing development. Always ensure that you adhere to the API guidelines to avoid having your access revoked.

Overview

The diagram below outlines the process flow that a standard payment will follow. These steps are explained in detail in the next few sections of this guide.

Get API Token

Create Request

Get Banks

Create Transaction

Bank Messages

Outcome

API Endpoints

Staging https://stagingapi.ozow.com
Live https://api.ozow.com

Common Headers

All requests excluding the "Get Token" request require the following HTTP headers.

Name Type Req Description
Authorization string (500) Y The token generated using the get token method. eg. Authorization: Bearer [token]
Content-Type string(50) N The format the response should be returned in e.g.
  • Accept: application/json
  • Accept: application/x-www-form-urlencoded
Accept string(50) Y The format the response should be returned in e.g.
  • Accept: application/json
  • Accept: application/xml

Error Object

All requests return the same error object to indicate if an error has occurred.

Name Type Description
Message string The error message
CanContinue bool Whether or not the process can continue.

Get API Token

All requests are authenticated using the token you will receive from this request. The same token can be used for all requests until it expires. The only content type supported by this request is "application/x-www-form-urlencoded".

Url /token
Method POST
Headers
Name Type Req Description
ApiKey string (50) Y Your merchant API key
Accept string(50) Y The format the response should be returned in e.g.
  • Accept: application/json
  • Accept: application/xml
URL Params N/A
Data Params
Name Type Req Description
grant_type string (50) Y Set as "password"
SiteCode string (50) Y The i-Pay site code for the site which the payment is being made to
Response Object
Name Type Description
access_token string (500) The token needed for subsequent requests
token_type string (50) The token type
expires_in string (50) The lifetime of the token in seconds
Request Example 
POST https://api.i-pay.co.za/token HTTP/1.1
ApiKey: EB5758F2C3B4DF3FF4F2669D5FF5B
Content-Type: application/x-www-form-urlencoded
grant_type=password&SiteCode=TSTSTE0001
Response Example 
{  
    "access_token":"x8EMsgirq_74gw11IY18Ugl...l-FW3vumkyTG0GfXudO9U",
    "token_type":"bearer",
    "expires_in":86399
}

Create Request

This is where you pass all the information regarding your request.

Url /secure/request/create
Method POST
Headers
 See common headers
URL Params N/A
Data Params
Name Type Req Description
SiteCode string (50) Y A unique code for the site currently in use. A site code is generated when adding a site in the Ozow Merchant Admin section.
CountryCode string (2) Y 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.
CurrencyCode string (3) Y 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 submitting the create request.
Amount decimal (9,2) Y The transaction amount. The amount is in the currency specified by the currency code posted.
TransactionReference string (50) Y The merchant's reference for the transaction.
BankReference string (20) Y This is the reference that will appear on your bank statement. It is advised that this is set to a unique value that enables you to match payments on your statement to transactions on your system. *Only alphanumeric characters, spaces and dashes are allowed.
Optional1
Optional2
Optional3
Optional4
Optional5		 string (50) N 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.
Customer string (100) N The customer’s name or identifier. Can be used to track customer behaviour.
NotifyUrl string (150) Y The URL that Ozow 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 it does not need to be dynamic. If a value is set in the merchant admin and in the request, the notification result will be sent to the URL set in the request.

* The outcome of pending transactions also gets posted to this URL.
IsTest bool Y Only false currently works for the payment API.
BankId guid N The bank that the payment should be made to. Merchant needs to be enabled to send through banking details (BankId, BankAccountNumber, BranchCode, BankAccountName) in the post, for most merchants this is setup when creating the merchant account. Possible values can be found in the bank list.
BankAccountNumber string (20) N The bank account number the payment should be made to.
BranchCode string (10) N The branch code for the bank account.
BankAccountName string (20) N The name of to be used for the bank account. Only alphanumeric characters and spaces allowed.
ProfileId guid N Only available to certain merchants.
ProfileToken guid N The token for the ProfileId.
HashCheck string (250) Y SHA512 hash used to ensure that certain fields in the message have not been altered after the hash was generated. Check the generate hash section below for more details on how to generate the hash.
Response Object
Name Type Description
requestId guid The identifier for the request that was created.
error Error Object If an error occurred this object will have details regarding the error.
Request Example 
POST https://api.ozow.com/secure/request/create HTTP/1.1
Authorization: Bearer x8EMsgirq_74...ddl-FW3vumkyTG0GfXudO9U
Accept: application/json
Content-Type: application/json
{  
    "SiteCode":"TSTSTE0001",
    "CountryCode":"ZA",
    "CurrencyCode":"ZAR",
    "Amount":"0.01",
    "TransactionReference":"TestApi",
    "BankReference":"TestApi",
    "Customer":"Api Test Customer",
    "NotifyUrl":"http://demo.ozow.com/notify.aspx",
    "IsTest":"false",
    "HashCheck":"f461ed21e54d2a23f71e7c130...4f54300bd54e36c4e0f"
}
Response Example 
{  
    "error":null,
    "requestId":"abf4a803-43a5-4a88-8031-4ba1d9068d92"
}

Generate Request Hash Check

Follow these steps to generate the hash check:

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

Hash Example

Here is an example of how a hash would be generated using the steps above and the values below.

SiteCode TSTSTE0001
CountryCode ZA
CurrencyCode ZAR
Amount 25.00
TransactionReference 123
BankReference ABC123
NotifyUrl http://demo.ozow.com/notify.aspx
IsTest false
  1. TSTSTE0001ZAZAR25.00123ABC123http://demo.ozow.com/notify.aspxfalse
  2. TSTSTE0001ZAZAR25.00123ABC123http://demo.ozow.com/notify.aspxfalse215114531AFF7134A94C88CEEA48E
  3. tstste0001zazar25.00123abc123http://demo.ozow.com/notify.aspxfalse215114531aff7134a94c88ceea48e
  4. eedcba106cd8fef3ba6cec5ec80de7d7d7fc90343028bf95b908718c671d0fe885ca08b206d788de009d237a93c18e66edf6ede3f5ca7057e23474106465dcc6

Get Banks

Get list of all valid banks for the request.

Url /secure/banks/:requestid
Method GET
Headers
 See common headers. No data is posted so the Content-Type header can be excluded.
URL Params
Name Type Description
requestId guid The request identifier (Same as returned by the Create Request method).
Data Params N/A
Response Object
Name Type Description
requestId guid The request identifier (Same as returned by the Create Request method).
banks Bank[] The banks applicable to the request.
error Error Object If an error occurred this object will have details regarding the error.
Bank Object
Name Type Description
id guid The bank identifier.
name string (50) The bank name.
subBanks Bank[] Some banks have more than one login method, if this is the case one of the sub banks will need to be chosen as an option for the Create Transaction method.
Request Example 
GET https://api.ozow.com/secure/banks/e4e62cde-0f94-4c6c-8a30-6fabef086012 HTTP/1.1
Accept: application/json
Authorization: Bearer x8EMsgirq_74gw1...Pjddl-FW3vumkyTG0GfXudO9U
Response Example 
{
    "requestId":"e4e62cde-0f94-4c6c-8a30-6fabef086012",
    "banks":[
        {
            "id":"3284a0ad-ba78-4838-8c2b-102981286a2b",
            "name":"ABSA",
            "subBanks":null
        },
        {
            "id":"ad7d8da4-1723-4066-94bb-6662d845e483",
            "name":"Standard Bank",
            "subBanks":[
                {
                    "id":"ad7d8da4-1723-4066-94bb-6662d845e483",
                    "name":"Standard Bank - Old",
                    "subBanks":null
                },
                {
                    "id":"ad8127c6-316d-459c-adcc-e62a214251fc",
                    "name":"Standard Bank - New",
                    "subBanks":null
                }
            ]
        },
        {
            "id":"913999fa-3a32-4e3d-82f0-a1df7e9e4f7b",
            "name":"Capitec Bank",
            "subBanks":null
        },
        {
            "id":"4816019c-3314-4c80-8b6b-b2cd16dcc4ec",
            "name":"FNB",
            "subBanks":null
        },
        {
            "id":"bf0561fd-4203-4a0c-9174-cb26fcd87a60",
            "name":"Nedbank",
            "subBanks":null
        },
        {
            "id":"4b45be85-b616-4bd1-9027-f8fcf8f9af7b",
            "name":"Investec",
            "subBanks":null
        }
    ],
    "error":null
}

Bank List

Bank selection screen can be completely customised and only preferred banks can be displayed. Using these values directly instead of the list returned by the Get Bank method will bypass any bank limit and other filtering setup in Ozow.

Below is a list of all banks and their identifiers, only banks that are marked with allow payments from can be used to create a transaction.

Name Id Payments From Payments To
ABSA 3284a0ad-ba78-4838-8c2b-102981286a2b
Capitec Bank 913999fa-3a32-4e3d-82f0-a1df7e9e4f7b
FNB 4816019c-3314-4c80-8b6b-b2cd16dcc4ec
Investec 4b45be85-b616-4bd1-9027-f8fcf8f9af7b
Nedbank bf0561fd-4203-4a0c-9174-cb26fcd87a60
Standard Bank ad7d8da4-1723-4066-94bb-6662d845e483
Standard Bank New ad8127c6-316d-459c-adcc-e62a214251fc
Bidvest Bank 29c5ee92-46ec-4879-8ad9-5cd3f5502727
Mercantile Bank 9e1917ad-29d1-4d11-80b5-0f6c33ae1083
RMB cc08d678-09cb-49c8-bcd8-2ec9e3bd0a82
Demo Bank ba18699f-8f5f-497b-9bcd-445133076408

Create Transaction

Once the user has selected their bank you need to create the transaction. This will return the first bank message response which will contain the bank login fields.

Url secure/transaction/create/:requestId/:bankId
Method GET
Headers
 See common headers. No data is posted so the Content-Type header can be excluded.
URL Params
Name Type Description
requestId guid The request identifier (Same as returned by the Create Request method).
bankId guid The identifier for the bank selected by the user.
Data Params N/A
Response Object See Bank Messages response object.
Request Example 
GET https://api.ozow.com/secure/transaction/create/5fabd...2653f/481601..16dcc4ec HTTP/1.1
Accept: application/json
Authorization: Bearer sNpM_uzQ8WerQvYuA...4IFTKHXaVc1sJ3FvJU
Response Example 
{
    "error":null,
    "display":{
        "title":"Login",
        "instructions":"Please enter your username and password",
        "inputFields":[
            {
                "name":"user",
                "defaultValue":"",
                "maxLength":100,
                "label":"Username",
                "type":"Text",
                "group":"Username"
            },
            {
                "name":"Password",
                "defaultValue":"",
                "maxLength":100,
                "label":"Password",
                "type":"Password",
                "group":"Password"
            }
        ],
        "type":"Form",                                             
        "actionText":"Login",
        "allowResend":false,
        "resendDelay":0
    },
    "transaction":{
        "id":"b86e12a1-80bb-48fd-951a-05af0853e403",
        "step":"Login",
        "status":null,
        "statusMessage":null,
        "receiptId":null
    }
}

Bank Messages

There are a number of messages that will be received and sent during the bank payment process.

Url /secure/payment/process/:paymentStep/:transactionId
Method POST
Headers
 See common headers
URL Params
Name Type Req Description
paymentStep string (50) Y The current step in the process. This would be the same as the last paymentStep value you received.
transactionId guid Y The transaction identifier.
Data Params
Type Req Description
Name-Value Pair[] N Bank Message responses contain a list of fields when input is required. This is an array of all the field names with the corresponding values received from the user.
Response Object
Name Type Description
display Display Object Contains display information.
transaction Transaction Object Contains transaction information.
error Error Object If an error occurred this object will have details regarding the error.
Display Object
Name Type Description
title string (150) Title text to indicate the current step to the user.
instructions string (500) Instructions to display to the user (Could contain html).
inputFields InputField[] List of input fields that need to be displayed to the user for input.
type string (20) Indicates what type of display needs to be shown to the user. See possible values.
actionText string (20) Text you can use for the continue button. If this is null or empty don't show a button for that step.
allowResend bool Whether to show a resend button to the user.
resendDelay int The number of seconds to delay showing the resend button to the user.
InputField Object

See field types section as properties will vary depending on the type.

Transaction Object
Name Type Description
id guid The transaction identifier.
step string (50) The current step of the payment. This value needs to be sent back to Ozow for each bank message request.
status string (50) The status of the transaction. The status field will only have a value once an outcome has been reached. See possible values.
statusMessage string (500) A user friendly message that can be displayed to the customer if the transaction was not successful.
receiptId guid A reference for the outcome of certain transaction statuses.
Request Example 
POST https://api.ozow.com/secure/payment/process/PaymentDetails/26d93705-...-10f632f86224 HTTP/1.1
Authorization: Bearer sNpM_uzQ8WerQvY...KHXaVc1sJ3FvJU
Accept: application/json
Content-Type: application/json
[{"name":"fromAnrfn","value":"-7668323"}]
Response Example 
{
    "error":null,
    "display":{
        "title":"FNB App Approve Request",
        "instructions":"Approve this transaction on the Banking App via Smart inContact",
        "inputFields":[],
        "type":"Prompt",
        "actionText":null,
        "allowResend":false,
        "resendDelay":0
    },
    "transaction":{
        "id":"26d93705-f3c8-4f1a-8fd3-10f632f86224",
        "step":"Await",
        "status":null,
        "statusMessage":null,
        "receiptId":null
    }
}

Display Types

The display types determine what needs to be displayed to the user.

Form

This requires you to display the input fields and a button (If the display action text property has a value).
Prompt

This is sent when the user needs to complete an action on their side e.g. Accepting a push message notification on their phone.

In this instance the message in the title and instruction properties need to be displayed in a way that catches the user's attention so they can acknowledge what action needs to be completed.

Busy

This is sent when the user has or has not completed the action in the prompt.

When receiving this display type you should display a busy indicator to the user.

Field Types

The field type will determine what type of field you display to the user.

Text This can be displayed to the user as a text input field.
Name Type Description
name string (100) The name of the input field. Needs to be the name used in the name-value pair sent back to Ozow.
defaultValue string (50) Value that should be prepopulated or selected in the field displayed to the user.
maxLength int The maximum length for text input fields.
label string (50) The label text that should be used when displaying the field to the user.
type string (50) "Text"
group string (50) A category for the field which could be used to display icons. See possible values.
Password

This can be displayed to the user as a password input field.

This would have the same properties as the text field type above except the value of the type property would be "Password".
Select There are a number of ways this can be displayed to a user e.g. Html select, custom picker, list of buttons (if there is no other input required for that step).
Name Type Description
name string (100) The name of the input field. Needs to be the name used in the name-value pair sent back to Ozow.
label string (50) The label text that should be used when displaying the field to the user.
options Option[] The list of options for the user to select from.
type string (50) Select
group string (50) A category for the field which could be used to display icons. See possible values.
Select Option Object
Name Type Description
text string (50) The display text for the option.
value string (50) The option's value which needs to be returned if the option is selected.
Partial Password

This is where a user only needs to enter certain character of their password. To determine which characters need to be entered, a field for each character is returned and the ones for which input is not required will have a disabled property set to true.

Name Type Description
label string (50) The label text that should be used when displaying the field to the user.
fields Field[] The fields for each character in the partial password.
type string (50) PartialPassword
Field Object
Name Type Description
name string (100) The name of the input field. Needs to be the name used in the name-value pair sent back to Ozow.
defaultValue string (50) Value that should be prepopulated in the field displayed to the user. This will only be returned for the fields where disabled is set to true.
maxLength int Only the value of 1 would be returned.
disabled bool Indicates whether input is required for this field or not.
Image

Used for CAPTCHA images

Name Type Description
base64 string Base64 string for the image.
type string (50) Image
group string (50) A category for the field which could be used to display icons. See possible values.

Field Groups

The use of icons for fields is not required, the list below is just an indication of icons you could use for the various field groups.

Username
Password
Account
Otp
Reference
Captcha
UserNumber

Field Encryption

All values for the "Login" step need to be encrypted using this encryption method before sending back to Ozow. The resulting bytes from the encryption should be converted to a Base64 string.

Algorithms AES
Mode CBC
Key Length 256 bits
Key

Your 32 character API key provided to you by Ozow.
IV Get the lowercase string of the transaction identifier. Do a SHA512 hash on the lowercase result and use the first 16 characters
Examples
private static function encrypt($data, $key, $iv_string) {
	while (strlen($key) < 32) {
		$key .= $key;
	}
	$iv = substr(hash('sha512', strtolower($iv_string)), 0, 16);
	$encrypted_bytes = openssl_encrypt($data, 'AES-256-CBC', substr($key, 0, 32), OPENSSL_RAW_DATA, $iv);
	return base64_encode($encrypted_bytes);
}
public static string EncryptAes(string data, string key, string ivString)
{
	byte[] dataBytes = Encoding.UTF8.GetBytes(data);
	byte[] encryptedBytes;
	string iv = GetSHA512Hash(ivString.ToLower()).Substring(0, 16);
	while (key.Length < 32)
	{
		key += key;
	}
	using (var aes = new AesCryptoServiceProvider())
	{
		aes.Key = Encoding.UTF8.GetBytes(key.Substring(0, 32));
		aes.Mode = CipherMode.CBC;
		aes.IV = Encoding.UTF8.GetBytes(iv);
		var encryptor = aes.CreateEncryptor();
		encryptedBytes = encryptor.TransformFinalBlock(dataBytes, 0, dataBytes.Length);
		aes.Clear();
	}
	return Convert.ToBase64String(encryptedBytes, 0, encryptedBytes.Length);
}

Outcome

Once you receive a bank message that contains a transaction status the transaction has been concluded and the status of the payment can be determined. You can trigger the relevant actions on your system based on the payment status received.

Status Types

Complete The payment was successfully completed
Cancelled The payment was cancelled as we could not proceed any further with the payment or the user cancelled.
Error A technical error occurred while processing the payment.
Abandoned No activity from the user for a set amount of time. The time varies for different steps.
PendingInvestigation An inconclusive result was received by the bank and the payment needs to be verified manually.
Pending The status cannot be determined as yet but will be posted to the notification URL as soon as it has been determined. Merchants not using the notification URL will receive a PendingInvestigation status.

Notification

Once the transaction has concluded a notification will be sent to the notification url specified in the Create Request method or configured in your Ozow merchant admin portal. If the status is "Pending", a notification will be sent again once the final status has been determined.

Name Type Description
SiteCode string (50) The site code sent to Ozow in the request post.
TransactionId guid The transaction identifier.
TransactionReference string (50) The merchant's transaction reference sent in the Create Request's TransactionReference variable.
Amount decimal (9,2) The payment amount. The amount is in the currency specified by the currency code.
Status string (50) The transaction status. See possible values.
Optional1
Optional2
Optional3
Optional4
Optional5		 string (50) Optional fields sent in the Create Request.
CurrencyCode string (3) The transaction currency code sent in the Create Request.
IsTest bool Whether or not the original request was a test request. Test requests are currently not available for this API so value will always be false.
StatusMessage string (500) Message regarding the status of the transaction. This field will not always have a value. This is a user friendly message that can be displayed to the user e.g. User cancelled transaction.
Hash string (250) SHA512 hash used to ensure that certain fields in the message have not been altered after the hash was generated. Check the generate hash section below for more details on how to validate the response variables using the hash.

Notification Hash Check

Follow these steps to generate the hash check:
  1. Concatenate the notification variables (excluding Hash) in the order they appear in the notification fields table above.
  2. Append your private key to the concatenated string. Your private key can be found in merchant details section of the merchant admin site.
  3. Convert the concatenated string to lowercase.
  4. Generate a SHA512 hash of the lowercase concatenated string.
  5. Compare generated hash to the Hash value received.

Get Transaction

Gets the status of a transaction. This can be used for polling to pick up abandoned transactions or can be used to verify the status of a transaction.

Url secure/transaction/status/:transactionId
Method GET
Headers
 See common headers. No data is posted so the Content-Type header can be excluded.
URL Params
Name Type Description
transactionId guid The transaction identifier.
Data Params N/A
Response Object
Name Type Description
transactionId guid The identifier for the transaction.
status string (50) The transaction status. See status types
statusUtcDate date The UTC date of the status.
receiptId guid The identifier for the transaction receipt.
error Error Object If an error occurred this object will have details regarding the error.
Request Example 
GET https://api.ozow.com/secure/transaction/status/ac53b87f-90ca-48b7-b821-55330a56379c HTTP/1.1
Accept: application/json
Authorization: Bearer jsK94mgvz17ZvZB...RZ7HF2dbJ_T-tTo
Response Example 
{  
   "error":null,
   "transactionId":"6f0bd243-1512-4c0a-b98f-75c8e1c06f93",
   "status":"Abandoned",
   "statusUtcDate":"2017-02-25T10:25:27.403",
   "receiptId":null
}

Terminate Transaction

Users should be given an option to cancel transactions or to change the bank they selected while on the login page.

Even though it might not seem completely necessary to instruct Ozow to terminate the transaction, it does help track customer behaviour as well as enable Ozow to make sure user banking sessions are not kept open any longer than necessary.

Cancel Transaction

Should be called when the user confirms that they would like to cancel the transaction or request.

Url secure/transaction/cancel/:transactionId
Method GET
Headers
 See common headers. No data is posted or returned so the Content-Type and Accept headers can be excluded.
URL Params
Name Type Description
transactionId guid The transaction identifier. The request identifier can be passed if the user has not selected a bank.
Data Params N/A
Response Object N/A
Request Example 
GET https://api.ozow.com/secure/transaction/cancel/ab57d2a2-192e-49da-a12d-c9c2362a856f HTTP/1.1
Authorization: Bearer jsK94mgvz17ZvZBOh...qWbRZ7HF2dbJ_T-tTo

Void Transaction

Should be called when the user chooses to change the bank selected and hasn't logged in.

Url secure/transaction/void/:transactionId
Method GET
Headers
 See common headers. No data is posted or returned so the Content-Type and Accept headers can be excluded.
URL Params
Name Type Description
transactionId guid The transaction identifier.
Data Params N/A
Response Object N/A
Request Example 
GET https://api.ozow.com/secure/transaction/void/ab57d2a2-192e-49da-a12d-c9c2362a856f HTTP/1.1
Authorization: Bearer jsK94mgvz17ZvZBOh...qWbRZ7HF2dbJ_T-tTo

Get Billing Transactions

Get list of all transaction eligible for billing in a given month for a merchant.

Url transaction/billing
Method GET
Headers
 See common headers. No data is posted so the Content-Type header can be excluded.
URL Params
Name Type Description
year int The year identifier for the month you would like to pull the list of billable transactions for.
month int The month identifier for the month you would like to pull the list of billable transactions for.
userid guid A valid user identifier who has billing admin rights for the authenticated merchant.
Data Params N/A
Response Object
Name Type Description
transactions object A collection of transactions with supplementary information.
Total decimal The total value of transactions in the collection.
count int The count of transactions in the collection.
Transactions Object
Name Type Description
items transaction[] Collection of transaction objects.
count int The count of transactions in the collection.
pageCount int Count of pages in the collection.
totalItemCount int The count of transactions in the collection.
pageNumber int Page Number if the results were paginated.
pageSize int How many items are included per page.
hasPreviousPage boolean True if there is a previous page to this one.
hasNextPage boolean True if there is a page after this one.
isFirstPage boolean True if this is the first page of a paginated collection.
isLastPage boolean True if this is the last page of a paginated collection.
firstItemOnPage int Record number of the first item in the collection.
lastItemOnPage int Record number of the last item in the collection.
Transaction Object
Name Type Description
id guid Unique transaction identifier.
merchantCode string Merchant Code of the transaction.
siteCode string Site Code of the transaction.
siteName string Site Name of the transaction.
bankFromName string Name of the bank from which the EFT originated.
bankToName string Name of the recipient bank.
amount decimal Value of the transaction.
bankReference string Bank reference of the transaction.
status string Transaction Status.
toAccount string Account number EFT was made to.
fromReference string Payer Reference.
toReference string Payee Reference.
paymentDate datetime Date payment was affected.
paymentDateUtc datetime UTC date payment was affected.
createdDate datetime Date and time the transaction was created.
createdDateUtc datetime UTC Date and time the transaction was created.
transactionReference string Transaction Reference
optional1 string
optional2 string
optional3 string
optional4 string
optional5 string
customer string Name of the customer on the payment request
subStatus string Transaction Sub-Status
Request Example 
GET https://api.ozow.com/secure/transaction/billing?year=2019&month=4&userid=XXXXXXX...XXXXXXXXXXX HTTP/1.1
Accept: application/json
Authorization: Bearer x8EMsgirq_74gw1...Pjddl-FW3vumkyTG0GfXudO9U
Response Example 

{
    "transactions": {
        "items": [
            {
                "id": "79f73fe1-f98a-4bbf-b835-8905731a29fa",
                "merchantCode": "TestMerch",
                "siteCode": "TSTSTE0001",
                "siteName": "test site",
                "bankFromName": "Demo Bank",
                "bankToName": "ABSA",
                "amount": 0.01,
                "bankReference": "",
                "status": "Complete",
                "toAccount": "12345678910",
                "fromReference": "test site",
                "toReference": "Test1",
                "paymentDate": "2019-04-02T11:29:10.947",
                "paymentDateUtc": "2019-04-02T09:29:10.947",
                "createdDate": "2019-04-02T11:27:06.097",
                "createdDateUtc": "2019-04-02T09:27:06.097",
                "transactionReference": "Test1",
                "optional1": "1",
                "optional2": "2",
                "optional3": "3",
                "optional4": "4",
                "optional5": "5",
                "customer": "Test Customer",
                "subStatus": "Unclassified"
            },
            {
                "id": "3f1ff77f-986a-443c-8357-1dc48d8ee383",
                "merchantCode": "TestMerch",
                "siteCode": "TSTSTE0001",
                "siteName": "test site",
                "bankFromName": "Nedbank",
                "bankToName": "Nedbank",
                "amount": 0.01,
                "bankReference": "20190402/NEDBANK/002118563618",
                "status": "Complete",
                "toAccount": "1148172386",
                "fromReference": "test site",
                "toReference": "Test1",
                "paymentDate": "2019-04-02T11:44:45.113",
                "paymentDateUtc": "2019-04-02T09:44:45.113",
                "createdDate": "2019-04-02T11:42:56.043",
                "createdDateUtc": "2019-04-02T09:42:56.043",
                "transactionReference": "Test1",
                "optional1": "1",
                "optional2": "2",
                "optional3": "3",
                "optional4": "4",
                "optional5": "5",
                "customer": "Test Customer",
                "subStatus": "Unclassified"
            }
        ],
        "count": 2,
        "pageCount": 1,
        "totalItemCount": 2,
        "pageNumber": 1,
        "pageSize": 2,
        "hasPreviousPage": false,
        "hasNextPage": false,
        "isFirstPage": true,
        "isLastPage": false,
        "firstItemOnPage": 1,
        "lastItemOnPage": 2
    },
    "total": 0.02,
    "count": 2
}

Terms of Use

The Ozow Payment API allows you to build Ozow's real-time EFT functionality directly into your website or app. This integration method gives you more flexibility but would require more effort than using the Ozow hosted method.

  • A "powered by Ozow" image must be displayed wherever the Ozow API is being used (directly or indirectly).
    Option 1
    Option 2
  • All transaction error messages returned from the API need to be displayed to the user in a modal to avoid any unnecessary support queries.
  • The following payment information must be displayed to the customer throughout the payment process:
    • The name of the merchant they are paying
    • The amount being paid
    • The merchant's reference for the transaction
  • Client's internet banking username and password cannot be stored.
  • The website capturing the username and password needs to have a valid SSL certificate at all times.
  • The merchant must continuously ensure that all necessary precautions are taken to ensure the safety of their client's sensitive information.
  • The merchant can in no way say that the solution is endorsed by any of the banks or use any bank logos.