Bulk job result notification · Payments API

POST Ozow sendsyour notification URL

Sent to the notifyUrl given on the create bulk payment request call, once the job has been processed.

compressedData holds the original data from the create call with the result fields for each record added, GZIP compressed.

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

compressedData goes into the hash as the compressed string exactly as it arrives, before you decompress it.

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/json

JobId string uuid required
The identifier for the bulk payment request job.
JobReference string required
The merchant reference for the job/batch that was passed in the create request.
max length100
Status string required
The status of the job. Possible values:
- Error - The bulk payment request job had encountered an error or the request data was not in the required format.
- Complete - The bulk payment request job had completed successfully.
- CompleteWithErrors - The bulk payment request job had completed but there were errors processing certain records.
CompressedData string required
A GZIP compressed JSON string of the JSON array of payment request fields. It carries the data from the create call with the result fields for each record added.

The hash is built from this string compressed, exactly as it arrives, so verify before you decompress.
Errors array of string required
A summary of how the job went, as a single line. Sent on every notification, a job that completed cleanly included, so its presence does not mean the job failed. Read the per record result fields inside CompressedData for what went wrong where.
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	`JobId`
2	`JobReference`
3	`Status`
4	`CompressedData`
5	Your private key

Important

Errors 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.

Notification

POST /your/notification/url HTTP/1.1
Content-Type: application/json

{
  "JobId": "2b6d9e1f-3a4c-4d5e-9f0a-1b2c3d4e5f6a",
  "JobReference": "BATCH-001",
  "Status": "CompleteWithErrors",
  "CompressedData": "H4sIAAAAAAAAA6tWSsvPV7JSSkxOTi0uzszPU6oFAKMKB/YZAAAA",
  "Errors": [
    "250 records processed | 248 successful | 2 errors."
  ],
  "Hash": "e7a2f9c6d3b0e5a8f1c4d7b2e9a6f3c0d5b8e1a4f7c2d9b6e3a0f5c8d1b4e7a2f9c6d3b0e5a8f1c4d7b2e9a6f3c0d5b8e1a4f7c2d9b6e3a0f5c8d1b4e7a2f9c6"
}

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

Verify

using System.Security.Cryptography;
using System.Text;
using System.Text.Json.Nodes;

// `notification` is the JSON body, parsed: JsonNode.Parse(body)
bool VerifyBulkJobResultNotification(
    JsonNode notification,
    string privateKey
)
{
    string Value(params string[] path)
    {
        JsonNode? node = notification;
        foreach (var key in path)
        {
            node = node?[key];
        }
        return node?.ToString() ?? "";
    }

    string inputString = string.Concat(
            Value("JobId"),
            Value("JobReference"),
            Value("Status"),
            Value("CompressedData"),
            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 JSON body, parsed: json_decode($body, true)
function verifyBulkJobResultNotification(
    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("JobId") .
        $value("JobReference") .
        $value("Status") .
        $value("CompressedData") .
        $privateKey
    );

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

const crypto = require("crypto");

// `notification` is the JSON body, parsed: JSON.parse(body)
function verifyBulkJobResultNotification(notification, privateKey) {
  const value = (...path) => {
    const node = path.reduce((current, key) => current?.[key], notification);
    return node === null || node === undefined ? "" : String(node);
  };

  const inputString = [
    value("JobId"),
    value("JobReference"),
    value("Status"),
    value("CompressedData"),
    privateKey,
  ].join("").toLowerCase();

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

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

import hashlib


# notification is the JSON body, parsed: json.loads(body)
def verify_bulk_job_result_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("JobId")
        + value("JobReference")
        + value("Status")
        + value("CompressedData")
        + private_key
    ).lower()

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