Refund notification · Payments API

POST Ozow sendsyour notification URL

Build with AI 1 package

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.

Migrate refunds from the Payments API to One APIEverything needed to move an existing refunds integration onto One API, with the legacy guide and its One API counterpart side by side.
View package

Sent to the notification URL given on the refund request, once the refund has either completed or failed.

Verify the hash field before acting on the contents. Concatenate the notification fields in the order they appear, excluding isRtc and hash, append your private key, lowercase the result, and compare a SHA512 of it against the value received.

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

RefundId string uuid required
The refund identifier.
TransactionId string uuid required
The transaction identifier of the transaction that is being refunded.
CurrencyCode string required
The refund currency. Will always be the same as the amount in the transaction.
max length3
Amount number double required
The refund amount, in the currency the currency code names. Written with two decimal places, which is the form the hash is built from.
IsRtc string required
An indication of whether RTC was used to pay the refund.
Status string required
The refund status. Sent as the name, not as a number, because the notification is form encoded and the status is written out in full.
values"Pending""Submitted""Complete""Failed""Cancelled""Returned""PendingInvestigation""Invalid""Error"
BankName string required
The name of the bank the refund was paid to.
max length50
AccountNumber string required
The masked account number payment was made to. The hash is built from the masked value, so hash what you received rather than the number you sent.
max length50
StatusMessage string
Message regarding the status of the refund. This field will not always have a value.
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.
max length128

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	`RefundId`
2	`TransactionId`
3	`CurrencyCode`
4	`Amount`, with two decimal places
5	`Status`
6	`BankName`
7	`AccountNumber`
8	`StatusMessage`
9	Your private key

Important

IsRtc arrives in the same body and is not part of the hash. Including it 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

Refund a paymentIssue a refund on the Payments API, the legacy path. Refunds are merchant-initiated backend operations, funded from your float balance.

Notification

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

RefundId=7f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f&TransactionId=c02dc1c9-a117-45cf-b375-d304cf434a52&CurrencyCode=ZAR&Amount=20.55&IsRtc=False&Status=Complete&BankName=Demo%20Bank&AccountNumber=123***789&StatusMessage=&Hash=8b4f1a7c2d9e6b3a0f5c8d1b4e7a2f9c6d3b0e5a8f1c4d7b2e9a6f3c0d5b8e1a4f7c2d9b6e3a0f5c8d1b4e7a2f9c6d3b0e5a8f1c4d7b2e9a6f3c0d5b8e1a4f7c

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 VerifyRefundNotification(
    IFormCollection notification,
    string privateKey
)
{
    string Value(string name) => notification[name].ToString();

    string inputString = string.Concat(
            Value("RefundId"),
            Value("TransactionId"),
            Value("CurrencyCode"),
            // 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("BankName"),
            Value("AccountNumber"),
            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 verifyRefundNotification(
    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("RefundId") .
        $value("TransactionId") .
        $value("CurrencyCode") .
        // Two decimals, invariant: the hash is built from 100.00, never 100.
        number_format((float) $value("Amount"), 2, ".", "") .
        $value("Status") .
        $value("BankName") .
        $value("AccountNumber") .
        $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 verifyRefundNotification(notification, privateKey) {
  const value = (...path) => {
    const node = path.reduce((current, key) => current?.[key], notification);
    return node === null || node === undefined ? "" : String(node);
  };

  const inputString = [
    value("RefundId"),
    value("TransactionId"),
    value("CurrencyCode"),
    // Two decimals, invariant: the hash is built from 100.00, never 100.
    Number(value("Amount") || 0).toFixed(2),
    value("Status"),
    value("BankName"),
    value("AccountNumber"),
    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_refund_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("RefundId")
        + value("TransactionId")
        + value("CurrencyCode")
        # Two decimals, invariant: the hash is built from 100.00, never 100.
        + f"{float(value('Amount') or 0):.2f}"
        + value("Status")
        + value("BankName")
        + value("AccountNumber")
        + value("StatusMessage")
        + private_key
    ).lower()

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