Request Payout

POST /requestpayout

Try it

Parameters

SiteCode*header

Bodyapplication/json

siteCode*amount*merchantReference*customerBankReference*^[A-Za-z0-9 -]+isRtc*notifyUrlbankingDetails.bankGroupId*bankingDetails.accountNumber*bankingDetails.branchCode*hashCheck*computed

Request sampleLanguage

curl -X POST 'https://payoutsapi.ozow.com/v1/requestpayout' \
  -H 'ApiKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'SiteCode: string' \
  -d '{
  "siteCode": "string",
  "amount": 50.2,
  "merchantReference": "string",
  "customerBankReference": "string",
  "isRtc": true,
  "notifyUrl": "https://example.com/",
  "bankingDetails": {
    "bankGroupId": "00000000-0000-0000-0000-000000000000",
    "accountNumber": "string",
    "branchCode": "string"
  },
  "hashCheck": "string"
}'

Response exampleStatus

{
  "payoutId": "00000000-0000-0000-0000-000000000000",
  "payoutStatus": {
    "status": 1,
    "subStatus": 100,
    "errorMessage": "<errorMessage>"
  }
}

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

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

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

Request a payout of the specified amount to the destination.

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 body

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
amount number double required
The payout amount in ZAR.
merchantReference string required
The merchant's reference for the transaction.
max length20
customerBankReference string required
The reference that will appear on the customer’s bank statement.

Only alphanumeric characters, spaces and dashes are allowed.
max length20pattern^[A-Za-z0-9 -]+
isRtc boolean required
Whether the payout should be processed as an RTC payout. RTC is not available in the staging environment so should always be set to false when testing in this environment
notifyUrl string uri
The URL that we should use to post all payout notifications.
max length150
bankingDetails BankDetails required
Payout destination banking details.
Fields of BankDetails
- bankGroupId string uuid required
  The unique bank identifier.
- accountNumber string required
  The bank account number the payment should be made to. The account number should be encrypted by the encryption method detailed above.
  max length21
- branchCode string required
  The destination bank branch code.
  max length10
Open BankDetails 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.

Responses

200 OK. The request reached the API, which is not the same as the payout being accepted. A rejected payout is also a 200, with the reason in `payoutStatus.errorMessage` and no `payoutId`. Check that field, not the status code.

payoutId string uuid required
A unique identifier that should be used to identify the payout.
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

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/requestpayout' \
  -H 'ApiKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'SiteCode: string' \
  -d '{
  "siteCode": "<siteCode>",
  "amount": 50.2,
  "merchantReference": "<merchantReference>",
  "customerBankReference": "<customerBankReference>",
  "isRtc": true,
  "notifyUrl": "https://example.com/notifyurl",
  "bankingDetails": {
    "bankGroupId": "00000000-0000-0000-0000-000000000000",
    "accountNumber": "<accountNumber>",
    "branchCode": "<branchCode>"
  },
  "hashCheck": "<hashCheck>"
}'

using var client = new HttpClient();

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

request.Content = new StringContent(@"{
  ""siteCode"": ""<siteCode>"",
  ""amount"": 50.2,
  ""merchantReference"": ""<merchantReference>"",
  ""customerBankReference"": ""<customerBankReference>"",
  ""isRtc"": true,
  ""notifyUrl"": ""https://example.com/notifyurl"",
  ""bankingDetails"": {
    ""bankGroupId"": ""00000000-0000-0000-0000-000000000000"",
    ""accountNumber"": ""<accountNumber>"",
    ""branchCode"": ""<branchCode>""
  },
  ""hashCheck"": ""<hashCheck>""
}", 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/requestpayout',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'ApiKey: YOUR_API_KEY',
        'Content-Type: application/json',
        'SiteCode: string',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "siteCode": "<siteCode>",
  "amount": 50.2,
  "merchantReference": "<merchantReference>",
  "customerBankReference": "<customerBankReference>",
  "isRtc": true,
  "notifyUrl": "https://example.com/notifyurl",
  "bankingDetails": {
    "bankGroupId": "00000000-0000-0000-0000-000000000000",
    "accountNumber": "<accountNumber>",
    "branchCode": "<branchCode>"
  },
  "hashCheck": "<hashCheck>"
}
JSON,
]);

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

const response = await fetch("https://payoutsapi.ozow.com/v1/requestpayout", {
  method: "POST",
  headers: {
    "ApiKey": "YOUR_API_KEY",
    "Content-Type": "application/json",
    "SiteCode": "string",
  },
  body: JSON.stringify({
    "siteCode": "<siteCode>",
    "amount": 50.2,
    "merchantReference": "<merchantReference>",
    "customerBankReference": "<customerBankReference>",
    "isRtc": true,
    "notifyUrl": "https://example.com/notifyurl",
    "bankingDetails": {
      "bankGroupId": "00000000-0000-0000-0000-000000000000",
      "accountNumber": "<accountNumber>",
      "branchCode": "<branchCode>"
    },
    "hashCheck": "<hashCheck>"
  }),
});

const data = await response.json();

import requests

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

payload = {
    "siteCode": "<siteCode>",
    "amount": 50.2,
    "merchantReference": "<merchantReference>",
    "customerBankReference": "<customerBankReference>",
    "isRtc": True,
    "notifyUrl": "https://example.com/notifyurl",
    "bankingDetails": {
        "bankGroupId": "00000000-0000-0000-0000-000000000000",
        "accountNumber": "<accountNumber>",
        "branchCode": "<branchCode>",
    },
    "hashCheck": "<hashCheck>",
}

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

Response

OK. The request reached the API, which is not the same as the payout being accepted. A rejected payout is also a 200, with the reason in `payoutStatus.errorMessage` and no `payoutId`. Check that field, not the status code.

{
  "payoutId": "00000000-0000-0000-0000-000000000000",
  "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.