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
Property | Type | Req. | 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. |
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. |
<?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
Property | Type | Req. | 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 is passed back to the merchant in the redirect and notification responses. |
IsTest | bool | No | Defaults 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 | 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: 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. |
StatusMessage | String (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. |
CreatedDate | DateTime | Transaction created date and time. |
PaymentDate | DateTime | Transaction payment date and time. |
SubStatus | String (50) | The transaction sub status for failed transactions. The value provides an indication as to why the payment failed. |
*BankName | String (50) | The masked account number the payment was made from. |
*MaskedAccountNumber | String (50) | The name of the bank the payment was made from. |
*SmartIndicators | String (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
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) | 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. |
StartDate | Date | Yes | The filter start date. Use format YYYY-MM-DD |
EndDate | Date | Yes | The 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.
Property | Type | Description |
---|---|---|
Id | String (50) | Ozow's unique reference for the transaction. |
CreatedDateUtc | DateTime | Date the transaction was created. |
SiteCode | String (50) | Unique code assigned to each merchant site. |
SiteName | String (50) | Merchant site name. |
BankFromName | String (50) | The bank the payment has been made from. |
BankToName | String (50) | The bank the payment has been made to. |
Amount | Decimal (9,2) | The transaction amount. |
Status | String (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. |
ToAccount | String (50) | The account number. |
ToReference | String (20) | The bank reference that was used to make the payment. |
PaymentDate | DateTime | Date the payment was successfully completed. |
PaymentDateUtc | DateTime | UTC date the payment was successfully completed. |
TransactionReference | String (50) | The merchant’s reference for the transaction. |
Customer | String (50) | Customer’s name |
Optional1 | String (50) | Optional 1 value received in the original transaction request. |
Optional2 | String (50) | Optional 2 value received in the original transaction request. |
Optional3 | String (50) | Optional 3 value received in the original transaction request. |
Optional4 | String (50) | Optional 4 value received in the original transaction request. |
Optional5 | String (50) | Optional 5 value received in the original transaction request. |
LastEvent | String (50) | Used for administration purposes, will be empty for most merchants. |
LastEventStatus | String (50) | Used for administration purposes, will be empty for most merchants. |
Updated about 1 year ago