Transaction notification · Payments API

POST Ozow sendsyour notification URL

Build with AI 2 packages

A build package is every page for one task, with the API operations they use. Copy the prompt into a coding assistant, or hand it the package itself: slim links to each page, full inlines all of them in one document.

Embed checkout in your own pageEverything needed to keep the customer on your site while they pay, as an iframe, a modal, or the Wallet SDK for Apple Pay and Google Pay, with the notification that actually confirms the payment.
View package
Migrate a payin from the Payments API to One APIEverything needed to move an existing redirect payin onto One API, with the legacy guide and its One API counterpart side by side.
View package

Sent to the notification URL once a transaction reaches a final status.

The URL comes from the NotifyUrl field on the payment request, or from the site configuration in the merchant admin site. Without one, no notification is sent.

Verify the Hash field before acting on the contents. A notification is an unauthenticated POST to a URL that anyone can call.

Authentication

Ozow sends no credential with this call, so this check is the only thing standing between a real delivery and a stranger’s. Verify the Hash field before acting on the contents: your notification URL is public, and anyone can post to it.

Payload

application/x-www-form-urlencoded

SiteCode string required
The site code sent to Ozow in the request post.
max length50
TransactionId string uuid required
The transaction identifier generated by Ozow.
max length50
TransactionReference string required
The merchant's transaction reference sent in the request post's TransactionReference variable.
max length50
Amount number double required
The transaction amount, always written with two decimal places. That is the form the hash is built from, so use the value exactly as it was posted.
Status string required
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 and 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.
max length50
Optional1 string
Optional fields sent in the request post.
max length50
Optional2 string
Optional fields sent in the request post.
max length50
Optional3 string
Optional fields sent in the request post.
max length50
Optional4 string
Optional fields sent in the request post.
max length50
Optional5 string
Optional fields sent in the request post.
max length50
CurrencyCode string required
The transaction currency code sent in the request post.
max length3pattern^[A-Z]+
IsTest string
Whether the transaction was a test transaction, sent as True or False. Part of the hash, so use the value exactly as it was posted.
max length5
StatusMessage string
A message about the status, empty for most transactions. Part of the hash, so an empty value still counts as a field and contributes an empty string.
max length500
Hash string required
SHA512 hash used to ensure that certain fields in the message have not been altered after the hash was generated. See the generate hash section for more details on how to validate the response variables using the hash.
max length128
SubStatus string
The transaction sub status for failed transactions. The value provides an indication as to why the payment failed.

Some examples: • Unclassified – Failure scenario has not been mapped • InsufficientFunds - User did not have sufficient funds available to complete the payment

While there are several sub-statuses, they have not been included here as they are strictly for reporting.
max length50
MaskedAccountNumber string
The masked account number the payment was made from.

If account number is 12 or more digits then the first and last four digits are unmasked e.g. 1234567898765 will be masked as 1234*****8765

If the account number is less than12 digits then the first and last 3 digits are left unmasked e.g. 123456789 will be masked as 123***789

This is not available by default and a request by the merchant must be submitted along with a justification for requiring this information.
max length50
BankName string
The name of the bank the payment was made from.
max length50
SmartIndicators string
Some Ozow merchants have requested this information as they use this in their own processes. The can be ignored unless you have a purpose and application for this information. The application of these indicators are for the merchant’s discretion and in isolation do not constitute any action to be taken by the merchant.

The field will contain a pipe delimited list of the following values if they are applicable e.g. HIGH_VALUE | FIRST_OZOW :
- HIGH_VALUE – If a soft limit is configured on the site and the amount paid is higher or equal to the configured limit
- FIRST_OZOW – First time a user has paid using Ozow
- FIRST_MERCHANT – First time a user has paid the merchant using Ozow
- NEW_OZOW – User has paid using Ozow for the first time in the past seven days
- NEW_MERCHANT - User has paid the merchant using Ozow for the first time in the past seven days
max length500

Verify the hash

Ozow sends no credential with this call, so Hash is the only thing that tells you the notification came from Ozow. Recompute it and compare before you act on anything else in the body.

Concatenate the fields in the table below, in that order. A field with no value contributes an empty string rather than being skipped.
Append your private key.
Convert the whole string, your private key included, to lowercase.
Take the SHA512 of it and write the digest as hexadecimal.
Compare that against Hash, ignoring case.

Position	Field
1	`SiteCode`
2	`TransactionId`
3	`TransactionReference`
4	`Amount`, with two decimal places
5	`Status`
6	`Optional1`
7	`Optional2`
8	`Optional3`
9	`Optional4`
10	`Optional5`
11	`CurrencyCode`
12	`IsTest`
13	`StatusMessage`
14	Your private key

Important

SubStatus, MaskedAccountNumber, BankName and SmartIndicators arrive in the same body and are not part of the hash. Including one of them gives a digest that never matches.

Hash calculator builds this string field by field, so you can compare it against the one your code produces.

Your response

200 Acknowledged. Return this once you have stored the notification.

No body.

Guides

Notification

POST /your/notification/url HTTP/1.1
Content-Type: application/x-www-form-urlencoded

SiteCode=YOUR_SITE_CODE&TransactionId=33857766-f29a-4a3a-a37e-66db3c42e439&TransactionReference=ORDER-001&Amount=100.55&Status=Complete&Optional1=&Optional2=&Optional3=&Optional4=&Optional5=&CurrencyCode=ZAR&IsTest=False&StatusMessage=&Hash=3c9ad55ad4bd0dcd2b0ea9c1e6b4b9d8f3e0f2a7c1d4b8e5a2f9c3d6b0e7a4f1c8d5b2e9a6f3c0d7b4e1a8f5c2d9b6e3a0f7c4d1b8e5a2f9c6d3b0e7a4f1c8d5&SubStatus=CustomerAccountError&MaskedAccountNumber=1234*****8765&BankName=Demo%20Bank&SmartIndicators=HIGH_VALUE%7CFIRST_OZOW

Built from the payload schema. Values are placeholders, not real data.

Verify

using System.Globalization;
using System.Security.Cryptography;
using System.Text;

// `notification` is the application/x-www-form-urlencoded body: Request.Form
bool VerifyTransactionNotification(
    IFormCollection notification,
    string privateKey
)
{
    string Value(string name) => notification[name].ToString();

    string inputString = string.Concat(
            Value("SiteCode"),
            Value("TransactionId"),
            Value("TransactionReference"),
            // Two decimals, invariant: the hash is built from 100.00, never 100.
            decimal.Parse(Value("Amount"), CultureInfo.InvariantCulture)
                .ToString("0.00", CultureInfo.InvariantCulture),
            Value("Status"),
            Value("Optional1"),
            Value("Optional2"),
            Value("Optional3"),
            Value("Optional4"),
            Value("Optional5"),
            Value("CurrencyCode"),
            Value("IsTest"),
            Value("StatusMessage"),
            privateKey
        ).ToLower();

    using SHA512 sha512 = SHA512.Create();
    var bytes = sha512.ComputeHash(Encoding.UTF8.GetBytes(inputString));
    var expected = Convert.ToHexString(bytes).ToLower();

    return expected == Value("Hash").ToLower();
}

<?php
// `notification` is the application/x-www-form-urlencoded body: $_POST
function verifyTransactionNotification(
    array $notification,
    string $privateKey
): bool {
    $value = function (string ...$path) use ($notification): string {
        $node = $notification;
        foreach ($path as $key) {
            $node = $node[$key] ?? null;
        }
        return $node === null ? "" : (string) $node;
    };

    $inputString = strtolower(
        $value("SiteCode") .
        $value("TransactionId") .
        $value("TransactionReference") .
        // Two decimals, invariant: the hash is built from 100.00, never 100.
        number_format((float) $value("Amount"), 2, ".", "") .
        $value("Status") .
        $value("Optional1") .
        $value("Optional2") .
        $value("Optional3") .
        $value("Optional4") .
        $value("Optional5") .
        $value("CurrencyCode") .
        $value("IsTest") .
        $value("StatusMessage") .
        $privateKey
    );

    return hash("sha512", $inputString)
        === strtolower($value("Hash"));
}

const crypto = require("crypto");

// `notification` is the application/x-www-form-urlencoded body: Object.fromEntries(new URLSearchParams(body))
function verifyTransactionNotification(notification, privateKey) {
  const value = (...path) => {
    const node = path.reduce((current, key) => current?.[key], notification);
    return node === null || node === undefined ? "" : String(node);
  };

  const inputString = [
    value("SiteCode"),
    value("TransactionId"),
    value("TransactionReference"),
    // Two decimals, invariant: the hash is built from 100.00, never 100.
    Number(value("Amount") || 0).toFixed(2),
    value("Status"),
    value("Optional1"),
    value("Optional2"),
    value("Optional3"),
    value("Optional4"),
    value("Optional5"),
    value("CurrencyCode"),
    value("IsTest"),
    value("StatusMessage"),
    privateKey,
  ].join("").toLowerCase();

  const expected = crypto
    .createHash("sha512")
    .update(inputString)
    .digest("hex");

  return expected === value("Hash").toLowerCase();
}

import hashlib


# notification is the application/x-www-form-urlencoded body: dict(request.form)
def verify_transaction_notification(notification, private_key):
    def value(*path):
        node = notification
        for key in path:
            node = node.get(key) if isinstance(node, dict) else None
        return "" if node is None else str(node)

    input_string = (
        value("SiteCode")
        + value("TransactionId")
        + value("TransactionReference")
        # Two decimals, invariant: the hash is built from 100.00, never 100.
        + f"{float(value('Amount') or 0):.2f}"
        + value("Status")
        + value("Optional1")
        + value("Optional2")
        + value("Optional3")
        + value("Optional4")
        + value("Optional5")
        + value("CurrencyCode")
        + value("IsTest")
        + value("StatusMessage")
        + private_key
    ).lower()

    expected = hashlib.sha512(input_string.encode()).hexdigest()
    return expected == value("Hash").lower()