Step 3: Check transaction status using API

Even though this step is optional, we highly recommend that it is completed, to ensure that responses received reflect the correct transaction status. This will eliminate the chance that anyone is able to spoof 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 that can be used to check the transaction status:

GetTransactionByReference
GetTransaction


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 is able to return multiple results. Ozow does not restrict the merchant from sending duplicate merchant references, though it is advised that a unique reference is sent per transaction. The number of results returned are limited to 10.

Parameters

PropertyType Req. Description
ApiKey (Http request header value)String (50)YesMerchant's API key, this value is available in the Ozow merchant admin section.
Accept (Http request header value)String (50)YesDetermines the format the response is returned in. Available values:

• application/json - Response is returned as json
• application/xml - Response is returned as xml
SiteCodeString (50)YesA 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.
TransactionReferenceString (50)YesThe merchant's reference for the transaction.
IsTestboolNoDefaults to false. Use true only to get results for test requests.
<?php

$api_key = "[YOUR API KEY]";
$site_code = "[YOUR SITE CODE]";
$transaction_reference = "Test1";
$base_url = "https://stagingapi.ozow.com/GetTransactionByReference";

$url = "{$base_url}?siteCode={$site_code}&transactionReference={$transaction_reference}";

$headers = array(
    "ApiKey" => $api_key
);

$options = array(
    "http" => array(
        "header" => "ApiKey: {$api_key}",
        "method" => "GET"
    )
);

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);

echo $response;

?>

import requests

api_key = "[YOUR API KEY]"
site_code = "[YOUR SITE CODE]"
transaction_reference = "Test1"
base_url = "https://stagingapi.ozow.com/GetTransactionByReference"

url = f"{base_url}?siteCode={site_code}&transactionReference={transaction_reference}"

headers = {"ApiKey": api_key}

response = requests.get(url, headers=headers)

print(response.content)

const apiKey = '[YOUR API KEY]';
const siteCode = '[YOUR SITE CODE]';
const transactionReference = 'Test1';
const baseUrl = 'https://stagingapi.ozow.com/GetTransactionByReference';

const url = `${baseUrl}?siteCode=${siteCode}&transactionReference=${transactionReference}`;

const headers = {
  'ApiKey': apiKey
};

fetch(url, {
  method: 'GET',
  headers: headers
}).then((response) => {
  return response.text();
}).then((data) => {
  console.log(data);
});

var client = new RestClient("https://stagingapi.ozow.com/GetTransactionByReference");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddParameter("siteCode", "[YOUR SITE CODE]");
request.AddParameter("transactionReference", "Test1");
request.AddHeader("ApiKey", "[YOUR API KEY]");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Response

Transaction[] - A successful call will return an array of the transaction object. The transaction object is described below.


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

PropertyTypeReq.Description
ApiKey (Http request header value)String (50)YesMerchant's API key, this value is available in the Ozow merchant admin section.
Accept (Http request header value)String (50)YesDetermines the format the response is returned in, available values:

• application/json - Response is returned as json
• application/xml - Response is returned as xml
SiteCodeString (50) YesA 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.
TransactionIdString (50)YesOzow's reference for the transaction. This is passed back to the merchant in the redirect and notification responses.
IsTestboolNoDefaults to false. Use true only to get results for test requests.
<?php

$api_key = "[YOUR API KEY]";
$site_code = "[YOUR SITE CODE]";
$transaction_id = "[YOUR TRANSACTION ID]";
$base_url = "https://stagingapi.ozow.com/GetTransaction";

$url = "{$base_url}?siteCode={$site_code}&transactionId={$transaction_id}";

$headers = array("ApiKey" => $api_key);

$options = array(
    "http" => array(
        "header" => "ApiKey: {$api_key}\r\n",
        "method" => "GET"
    )
);

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);

echo $response;

?>
const string apiKey = "[YOUR API KEY]";
const string siteCode = "[YOUR SITE CODE]";
const string transactionId = "[YOUR TRANSACTION ID]";
const string baseUrl = "https://stagingapi.ozow.com/GetTransaction";

var client = new RestClient($"{baseUrl}?siteCode={siteCode}&transactionId={transactionId}");
client.Timeout = -1;

var request = new RestRequest(Method.GET);
request.AddHeader("ApiKey", apiKey);

var response = client.Execute(request);

Console.WriteLine(response.Content);
const apiKey = "[YOUR API KEY]";
const siteCode = "[YOUR SITE CODE]";
const transactionId = "[YOUR TRANSACTION ID]";

const requestOptions = {
  method: "GET",
  headers: {
    ApiKey: apiKey,
  },
  redirect: "follow",
};

fetch(
  `https://stagingapi.ozow.com/GetTransaction?siteCode=${siteCode}&transactionId=${transactionId}`,
  requestOptions
).then((response) => response.text())
 .then((result) => console.log(result))
 .catch((error) => console.log("error", error));
import requests

api_key = "[YOUR API KEY]"
site_code = "[YOUR SITE CODE]"
transaction_id = "[YOUR TRANSACTION ID]"
base_url = "https://stagingapi.ozow.com/GetTransaction"

url = f"{base_url}?siteCode={site_code}&transactionId={transaction_id}"

headers = {"ApiKey": api_key}

response = requests.get(url, headers=headers)

print(response.content)

Response

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


Transaction object

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

Property TypeDescription
TransactionIdString (50)Ozow's unique reference for the transaction.
MerchantCodeString (50)Unique code assigned to each merchant.
SiteCodeString (50)Unique code assigned to each merchant site.
TransactionReferenceString (50)Merchant's transaction reference.
CurrencyCodeString (3)The transaction currency code.
AmountDecimal (9,2)The transaction amount.
StatusString (50)The transaction status. Possible values are:

1. Complete - The payment was successful.
2. Cancelled - The payment was cancelled.
3. Error - An error occurred while processing the payment.
4. Abandoned – The payment was abandoned.
5. PendingInvestigation – An inconclusive result was received by the bank. The payment needs to be verified manually.
6. Pending – The status cannot be determined as yet but will be reposted to the notification URL as soon as it has been determined. Merchants not using the notification URL will receive a PendingInvestigation status.
StatusMessageString (150)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.
CreatedDateDateTimeTransaction created date and time.
PaymentDateDateTimeTransaction payment date and time.
SubStatusString (50)The transaction sub status for failed transactions. The value provides an indication as to why the payment failed.
*BankNameString (50)The masked account number the payment was made from.
*MaskedAccountNumberString (50) The name of the bank the payment was made from.
*SmartIndicatorsString (500) Refer to SmartIndicators field in notification response.*

🚧

Warning

*These are currently only populated for GetTransactionByReference API call but are blank for the GetTransaction API call.


Extract transaction report using API

GetTransactionReport

https://api.ozow.com/GetTransactionReport?siteCode={siteCode}&startDate={startDate}&endDate={endDate}

This method can be called to get all transactions for a merchant site in a particular date range.

Parameters

Property Type Req.Description
ApiKey (Http request header value)String (50)YesMerchant's API key, this value is available in the Ozow merchant admin section.
Accept (Http request header value)String (50)YesDetermines the format the response is returned in, available values:

• application/json - Response is returned as json
• application/xml - Response is returned as xml
SiteCodeString (50) YesA 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.
StartDateDateYesThe filter start date. Use format YYYY-MM-DD
EndDateDateYesThe filter end date. Use format YYYY-MM-DD

TransactionModel[] - A successful call will return an array of the transaction model object. The transaction model object is described below.


TransactionModel object

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

PropertyTypeDescription
IdString (50)Ozow's unique reference for the transaction.
CreatedDateUtcDateTimeDate the transaction was created.
SiteCodeString (50)Unique code assigned to each merchant site.
SiteNameString (50)Merchant site name.
BankFromNameString (50)The bank the payment has been made from.
BankToNameString (50)The bank the payment has been made to.
AmountDecimal (9,2)The transaction amount.
StatusString (50)The transaction status. Possible values are:

1. Complete - The payment was successful.
2. Cancelled - The payment was cancelled.
3. Error - An error occurred while processing the payment.
4. Abandoned – The payment was abandoned.
5. PendingInvestigation – An inconclusive result was received by the bank. The payment needs to be verified manually.
6. Pending – The status cannot be determined as yet but will be reposted to the notification URL as soon as it has been determined. Merchants not using the notification URL will receive a PendingInvestigation status.
ToAccountString (50)The account number.
ToReferenceString (20)The bank reference that was used to make the payment.
PaymentDateDateTimeDate the payment was successfully completed.
PaymentDateUtcDateTime UTC date the payment was successfully completed.
TransactionReferenceString (50)The merchant’s reference for the transaction.
CustomerString (50)Customer’s name
Optional1String (50)Optional 1 value received in the original transaction request.
Optional2String (50)Optional 2 value received in the original transaction request.
Optional3String (50)Optional 3 value received in the original transaction request.
Optional4String (50)Optional 4 value received in the original transaction request.
Optional5String (50)Optional 5 value received in the original transaction request.
LastEventString (50)Used for administration purposes, will be empty for most merchants.
LastEventStatusString (50)Used for administration purposes, will be empty for most merchants.

What’s Next