Integrating Ozow as an automated payout provider via a RESTful API can be achieved with the following sequence of steps:
- Step 1: Check the payout availability for the destination bank, including the realtime clearing (RTC) feature (optional, but recommended for a better client experience)
- Step 2: Submit a payout request via Ozow API
- Step 3: Ozow requires each merchant to build a web-hook API end-point which will be triggered in order to verify each payout request
- Step 4: Check payout status using Ozow's API (optional but recommended)
Before you start
Please make sure to use your live API Key after testing, and once you are ready to go live.
The current API version is: v1.0
Ozow provides a mock implementation for each API endpoint, which can be utilised during the development phase of a payout integration. These mock endpoints enable a merchant that validation rules and business logic is implemented correctly and tested prior to an actual payout taking place. The endpoints are safe to consume and no monies will be transferred. In order to consume a mock endpoint, the "mock" route is added to the environment base urls:
Ozow’s payout API authentication requires two headers to be added for each endpoint request. The following headers are required:
- SiteCode - A unique code for the site currently in use. A site code is generated when adding a site in the Ozow merchant admin section.
- APIKey – A new payout API specific key will be provided by Ozow.
API Key: EB5758F2C3B4DF3FF4F2669D5FF5B
For security and verification purposes
Ozow requires that the merchant encrypts the destination account number using a unique encryption key per payout request, as described below:
The Advanced Encryption Standard (AES) should be used to encrypt the destination bank account. More information can be obtained on Wikipedia and on Microsoft’s .Net Cryptography site.
The following AES parameters should be used:
- Key size: 256
- Block Cypher Mode of operation: Cipher block chaining (CBC)
- Padding: PKCS7
The initialisation vector (IV) should be an SHA512 hash of the following (Note: the IV hash length should be 16 bytes. If the SHA512 has is longer than 16 bytes then the first 16 bytes should be used as the IV):
- Merchant reference
- Amount in cents (e.g 10000 for R100.00)
- Encryption key
The merchant will need to persist the encryption key per payout request.
Follow these steps to generate the hash check:
- Concatenate the post variables (excluding HashCheck) in the order they appear in the post variables table.
- Append your API key to the concatenated string.
- Convert the concatenated string to lowercase.
- Generate a SHA512 hash of the lowercase concatenated string.
Amount: 2500 (ie. R25.00 converted to cents)
This method can be called to retrieve the set of banks that are available for making payouts to.
The call returns a list of banks with a unique identifier (BankGroupId) per bank. The BankGroupId is utilised as an input parameter to check payout availability for a particular bank, as well as to identify the destination bank for a payout.
A successful call will return a list of available banks. Each bank is represented by a BankGroup object, which is described as below.
|Guid||A unique bank identifier.|
|String (100)||The bank name.|
|String (10)||The universal branch code that can be used to make when requesting a payout.|
Updated 22 days ago