Get Payouts by Reference

POST /getpayoutbyreference

Try it

Parameters

SiteCode*header

Bodyapplication/json

pageSizepageIndexsearchFieldscomma separatedsearchStringsortFieldminAmountmaxAmountdateFromdateToisRtcbulkReference

Request sampleLanguage

curl -X POST 'https://payoutsapi.ozow.com/v1/getpayoutbyreference' \
  -H 'ApiKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'SiteCode: string' \
  -d '{
  "pageSize": 1,
  "pageIndex": 1,
  "searchFields": [
    "0"
  ],
  "searchString": "string",
  "sortField": "0",
  "minAmount": 10.5,
  "maxAmount": 10.5,
  "dateFrom": "2026-01-15T09:30:00Z",
  "dateTo": "2026-01-15T09:30:00Z",
  "isRtc": true,
  "bulkReference": "string"
}'

Response exampleStatus

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "amount": 55,
    "siteCode": "<siteCode>",
    "merchantReference": "<merchantReference>",
    "customerBankReference": "<customerBankReference>",
    "notifyUrl": "https://example.com/notifyurl",
    "isRtc": true,
    "bankingDetails": {
      "bankGroupId": "00000000-0000-0000-0000-000000000000",
      "accountNumber": "<accountNumber>",
      "branchCode": "<branchCode>"
    },
    "payoutStatus": {
      "status": 1,
      "subStatus": 100,
      "errorMessage": "<errorMessage>"
    }
  }
]

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

POSThttps://payoutsapi.ozow.com/v1/getpayoutbyreferenceProduction

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

Search a site's payouts. Filtering on the merchant reference is the common case, and is what a status check falls back to when the payout identifier was not recorded.

Authentication

API key in the ApiKey header

Header parameters

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

Request bodyrequired

pageSize integer
How many payouts to return per page. Below 1 is treated as 1.
pageIndex integer
Which page to return, counting from 1. Below 1 is treated as 1.
searchFields array of PayoutField
Which fields searchString is matched against.
searchString string
The value to search for in the fields named by searchFields.
sortField PayoutField
The field to order the results by.
values01234
minAmount number
Exclude payouts below this amount.
maxAmount number
Exclude payouts above this amount.
dateFrom string date-time
Exclude payouts created before this moment.
dateTo string date-time
Exclude payouts created after this moment.
isRtc boolean
Return only real time clearing payouts.
bulkReference string
Return only payouts from the bulk upload with this reference.

Responses

200 OK

X-Pagination header
Pagination metadata for the result set, as a JSON object. Carries the page counts and the flags for whether further pages exist.

array of PayOut

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.

Request

curl -X POST 'https://payoutsapi.ozow.com/v1/getpayoutbyreference' \
  -H 'ApiKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'SiteCode: string' \
  -d '{
  "pageSize": 1,
  "pageIndex": 1,
  "searchFields": [
    0
  ],
  "searchString": "<searchString>",
  "sortField": 0,
  "minAmount": 10.5,
  "maxAmount": 10.5,
  "dateFrom": "2026-01-15T09:30:00Z",
  "dateTo": "2026-01-15T09:30:00Z",
  "isRtc": true,
  "bulkReference": "<bulkReference>"
}'

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://payoutsapi.ozow.com/v1/getpayoutbyreference");
request.Headers.Add("ApiKey", "YOUR_API_KEY");
request.Headers.Add("SiteCode", "string");

request.Content = new StringContent(@"{
  ""pageSize"": 1,
  ""pageIndex"": 1,
  ""searchFields"": [
    0
  ],
  ""searchString"": ""<searchString>"",
  ""sortField"": 0,
  ""minAmount"": 10.5,
  ""maxAmount"": 10.5,
  ""dateFrom"": ""2026-01-15T09:30:00Z"",
  ""dateTo"": ""2026-01-15T09:30:00Z"",
  ""isRtc"": true,
  ""bulkReference"": ""<bulkReference>""
}", Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payoutsapi.ozow.com/v1/getpayoutbyreference',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'ApiKey: YOUR_API_KEY',
        'Content-Type: application/json',
        'SiteCode: string',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "pageSize": 1,
  "pageIndex": 1,
  "searchFields": [
    0
  ],
  "searchString": "<searchString>",
  "sortField": 0,
  "minAmount": 10.5,
  "maxAmount": 10.5,
  "dateFrom": "2026-01-15T09:30:00Z",
  "dateTo": "2026-01-15T09:30:00Z",
  "isRtc": true,
  "bulkReference": "<bulkReference>"
}
JSON,
]);

$response = curl_exec($curl);
curl_close($curl);

const response = await fetch("https://payoutsapi.ozow.com/v1/getpayoutbyreference", {
  method: "POST",
  headers: {
    "ApiKey": "YOUR_API_KEY",
    "Content-Type": "application/json",
    "SiteCode": "string",
  },
  body: JSON.stringify({
    "pageSize": 1,
    "pageIndex": 1,
    "searchFields": [
      0
    ],
    "searchString": "<searchString>",
    "sortField": 0,
    "minAmount": 10.5,
    "maxAmount": 10.5,
    "dateFrom": "2026-01-15T09:30:00Z",
    "dateTo": "2026-01-15T09:30:00Z",
    "isRtc": true,
    "bulkReference": "<bulkReference>"
  }),
});

const data = await response.json();

import requests

headers = {
    "ApiKey": "YOUR_API_KEY",
    "Content-Type": "application/json",
    "SiteCode": "string",
}

payload = {
    "pageSize": 1,
    "pageIndex": 1,
    "searchFields": [
        0,
    ],
    "searchString": "<searchString>",
    "sortField": 0,
    "minAmount": 10.5,
    "maxAmount": 10.5,
    "dateFrom": "2026-01-15T09:30:00Z",
    "dateTo": "2026-01-15T09:30:00Z",
    "isRtc": True,
    "bulkReference": "<bulkReference>",
}

response = requests.post(
    "https://payoutsapi.ozow.com/v1/getpayoutbyreference",
    headers=headers,
    json=payload,
)

Response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "amount": 55,
    "siteCode": "<siteCode>",
    "merchantReference": "<merchantReference>",
    "customerBankReference": "<customerBankReference>",
    "notifyUrl": "https://example.com/notifyurl",
    "isRtc": true,
    "bankingDetails": {
      "bankGroupId": "00000000-0000-0000-0000-000000000000",
      "accountNumber": "<accountNumber>",
      "branchCode": "<branchCode>"
    },
    "payoutStatus": {
      "status": 1,
      "subStatus": 100,
      "errorMessage": "<errorMessage>"
    }
  }
]

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

Bad Request. The request did not reach the API. A required header or query parameter is missing, or the body does not match the expected shape.

{
  "message": "<message>"
}

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

Forbidden. The `SiteCode` and `ApiKey` pair was not accepted.

{
  "message": "<message>"
}

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

Internal Server Error. The gateway could not reach the service or the integration failed. A failure inside the service is not this one. Those come back as a 200 with the reason in the payload, because the gateway maps every integration response it has no other rule for onto 200.

{
  "message": "<message>"
}

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