Payout notification · Payouts 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.

Send a payoutEverything needed to pay money out to a customer's bank account or voucher with the Payouts API, including how to exercise the failure paths before going live.
View package

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

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

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

The same payout can be notified more than once. Ozow works to avoid duplicates and cannot guarantee their absence, so your handler must be idempotent: a repeated notification for a payout you have already processed must not credit or debit anyone a second time.

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 hashCheck field before acting on the contents: your notification URL is public, and anyone can post to it.

Payload

application/json

payoutId string uuid
Ozow's unique reference for the payout.
siteCode string required
A unique code for the site currently in use. A site code is generated when adding a site in the Ozow merchant admin section. [Please contact support for SiteCode - support@ozow.com]
max length50
merchantReference string required
The merchant's reference for the transaction.
max length20
customerMerchantReference string required
The reference that will be prepopulated in the "their reference" field in the customers online banking site. This will be the payout reference that appears on the merchant’s bank statement and can be used for recon purposes.
max length20pattern^[A-Za-z0-9 -]+
payoutStatus PayoutStatus required
Payout status.
Fields of PayoutStatus
- status integer int32 required
  The payout status.
  
  1: Payout Received. The payout has been received.
  
  2: Verification. The payout is being verified.
  
  3: Payout Submitted For Processing. The payout is being processed.
  
  4: Payout Processing Error. There was an error with the payout.
  
  5: Payout Completed. The payout has been completed.
  
  6: Payout Pending Investigation. The payout is being investigated.
  
  7: Payout Pending Cancellation. Cancellation has been requested and is not yet settled.
  
  90: Payout Returned. The payout could not be paid into the recipient account.
  
  99: Payout Cancelled. The payout was cancelled.
  values12345679099min0
- subStatus integer required
  The payout sub status. Possible values are:
  
  100: Payout_Unclassified – No sub status.
  
  101: Payout_ValidationFailed – Request validation failed and error description will be in the ErrorMessage field.
  
  201: Verification_Pending – Awaiting webook verification.
  
  202: Verification_Failed – The verification webhook returned a failed.
  
  203: Verification_Success – Successful payout verification via webhook.
  
  204: Verification_Error – Unable to reach the verification webhook.
  
  205: Verification_AccountNumberDecryptionFailed – Decryption of the account number failed using the key received via webhook.
  
  301: SubmittedForProcessing_PayoutAddedToBatch – The payout has been added to the payout batch.
  
  302: SubmittedForProcessing_PayoutSubmittedToBank – The payout batch has been processed and submitted to the bank.
  
  303: SubmittedForProcessing_PayoutSubmittedToPpi – Payout submitted for processing.
  
  401: PayoutProcessingError_PayoutRejected – The payout has been rejected by the bank.
  
  402: PayoutProcessingError_PayoutCancelled – The payout has been cancelled.
  
  403: PayoutProcessingError_Insufficient_Balance – Insufficient balance.
  
  404: PayoutProcessingError_PayoutInternalError.
  
  405: PayoutProcessingError_InvalidAccountNumber – The payout has an invalid account number.
  
  601: PayoutPendingInvestigation_AmountMismatch – The payout failed due to mismatch in amounts.
  
  9001: PayoutReturned_Unpaid – Rejected by destination bank.
  
  9901: Cancellation_AddedToBatch – Cancellation request added to batch for processing.
  
  9902: Cancellation_SubmittedToBank – Cancellation request has been submitted to the bank.
  
  9903: Cancellation_RejectedByBank – Cancellation request has been rejected by the bank.
  
  9904 - Cancellation_AccountNumberValidationFailed – CDV account number validation failed.
  min0
- errorMessage string
  Error message generated when validating the request.
  max length250
Open PayoutStatus on its own page
hashCheck string required
SHA512 hash used to ensure that certain fields in the message have not been altered after the hash was generated. Check the generate hash section in the documentation for more details on how to generate the hash.

Verify the hash

Ozow sends no credential with this call, so hashCheck 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 API key.
For a voucher payout, append the voucher pin after your API key.
Convert the whole string, your API key included, to lowercase.
Take the SHA512 of it and write the digest as hexadecimal.
Compare that against hashCheck, ignoring case.

Position	Field
1	`payoutId`
2	`siteCode`
3	`merchantReference`
4	`customerMerchantReference`
5	`payoutStatus.status`
6	`payoutStatus.subStatus`
7	Your API key
8	`voucherPin`, for a voucher payout only

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

Send a payoutTransfer funds to a recipient's bank account with the Payouts API. There is no customer-facing step, so the whole integration lives in your backend.

Notification

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

{
  "payoutId": "4e8a1b2c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
  "siteCode": "YOUR_SITE_CODE",
  "merchantReference": "PAYOUT-001",
  "customerMerchantReference": "SALARY MAR",
  "payoutStatus": {
    "status": 1,
    "subStatus": 100,
    "errorMessage": "<errorMessage>"
  },
  "hashCheck": "5d2e8a1f4b7c0d3e6a9f2c5b8e1a4d7f0c3b6e9a2d5f8c1b4e7a0d3f6c9b2e5a8d1f4c7b0e3a6d9f2c5b8e1a4d7f0c3b6e9a2d5f8c1b4e7a0d3f6c9b2e5a8d1f"
}

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)
// A voucher payout appends its pin after the key. Leave it empty for a
// bank payout: a field with no value contributes nothing.
bool VerifyNotificationResponse(
    JsonNode notification,
    string apiKey,
    string voucherPin = ""
)
{
    string Value(params string[] path)
    {
        JsonNode? node = notification;
        foreach (var key in path)
        {
            node = node?[key];
        }
        return node?.ToString() ?? "";
    }

    string inputString = string.Concat(
            Value("payoutId"),
            Value("siteCode"),
            Value("merchantReference"),
            Value("customerMerchantReference"),
            Value("payoutStatus", "status"),
            Value("payoutStatus", "subStatus"),
            apiKey,
            voucherPin
        ).ToLower();

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

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

<?php
// `notification` is the JSON body, parsed: json_decode($body, true)
// A voucher payout appends its pin after the key. Leave it empty for a
// bank payout: a field with no value contributes nothing.
function verifyNotificationResponse(
    array $notification,
    string $apiKey,
    string $voucherPin = ""
): 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("payoutId") .
        $value("siteCode") .
        $value("merchantReference") .
        $value("customerMerchantReference") .
        $value("payoutStatus", "status") .
        $value("payoutStatus", "subStatus") .
        $apiKey .
        $voucherPin
    );

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

const crypto = require("crypto");

// `notification` is the JSON body, parsed: JSON.parse(body)
// A voucher payout appends its pin after the key. Leave it empty for a
// bank payout: a field with no value contributes nothing.
function verifyNotificationResponse(notification, apiKey, voucherPin = "") {
  const value = (...path) => {
    const node = path.reduce((current, key) => current?.[key], notification);
    return node === null || node === undefined ? "" : String(node);
  };

  const inputString = [
    value("payoutId"),
    value("siteCode"),
    value("merchantReference"),
    value("customerMerchantReference"),
    value("payoutStatus", "status"),
    value("payoutStatus", "subStatus"),
    apiKey,
    voucherPin,
  ].join("").toLowerCase();

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

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

import hashlib


# notification is the JSON body, parsed: json.loads(body)
# A voucher payout appends its pin after the key. Leave it empty for a
# bank payout: a field with no value contributes nothing.
def verify_notification_response(notification, api_key, voucher_pin=""):
    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("payoutId")
        + value("siteCode")
        + value("merchantReference")
        + value("customerMerchantReference")
        + value("payoutStatus", "status")
        + value("payoutStatus", "subStatus")
        + api_key
        + voucher_pin
    ).lower()

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