Payouts integration

Payouts in a jiffy with our step-by-step guide

Overview

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.


Service details

Version

The current API version is: v1.0

Environment base urls

Production: https://payoutsapi.ozow.com/{version}

Development: https://stagingpayoutsapi.ozow.com/{version}

Mock API endpoint base urls

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:

Production: https://payoutsapi.ozow.com/mock/{version}

Development: https://stagingpayoutsapi.ozow.com/mock/{version}

Authentication

Ozow’s payout API authentication requires two headers to be added for each endpoint request. The following headers are required:

  1. 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.
  2. APIKey  – A new payout API specific key will be provided by Ozow.

Test account details

SiteCode: TSTSTE0001

API Key: EB5758F2C3B4DF3FF4F2669D5FF5B


Account number encryption

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:

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

  2. The following AES parameters should be used:

    • Key size: 256
    • Block Cypher Mode of operation: Cipher block chaining (CBC)
    • Padding: PKCS7
  3. 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
  4. The merchant will need to persist the encryption key per payout request.


Message integrity checks

Post hash check

Follow these steps to generate the hash check:

  1. Concatenate the post variables (excluding HashCheck) in the order they appear in the post variables table.
  2. Append your API key to the concatenated string.
  3. Convert the concatenated string to lowercase.
  4. Generate a SHA512 hash of the lowercase concatenated string.

Hash check example

SiteCode: TSTSTE0001
Amount: 2500 (ie. R25.00 converted to cents)
MerchantReference: 123
CustomerBankReference: ABC123
IsRTC: true
NotifyUrl: http://demo.ozow.com/notify.aspx
BankingDetails.BankGroupId: 13999FA-3A32-4E3D-82F0-A1DF7E9E4F7B
BankingDetails.AccountNumber: ff313a955ad9a8ddff32cb734d49fbcddd8eeb1e235009d59a801bc5af78270cfd
BankingDetails.BranchCode: 632005

  1. TSTSTE00012500123ABC123truehttp://demo.ozow.com/notify.aspx13999FA-3A32-4E3D-82F0-A1DF7E9E4F7Bff313a955ad9a8ddff32cb734d49fbcddd8eeb1e235009d59a801bc5af78270cfd632005
  2. TSTSTE00012500123ABC123truehttp://demo.ozow.com/notify.aspx13999FA-3A32-4E3D-82F0-A1DF7E9E4F7Bff313a955ad9a8ddff32cb734d49fbcddd8eeb1e235009d59a801bc5af78270cfd632005215114531AFF7134A94C88CEEA48E
  3. tstste00012500123abc123truehttp://demo.ozow.com/notify.aspx13999fa-3a32-4e3d-82f0-a1df7e9e4f7bff313a955ad9a8ddff32cb734d49fbcddd8eeb1e235009d59a801bc5af78270cfd632005215114531aff7134a94c88ceea48e
  4. 2f6d04be5a0b1f87df4c3ae84624c71690fccb58abe8620edff5b28be8969d29648f844ccd5afcc8de465aec75105bf83e57d4dd1cf12afd8fa45aebb12241c6

Operations

Get available banks

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.

{baseUrl}/getavailablebanks

Response

A successful call will return a list of available banks. Each bank is represented by a BankGroup object, which is described as below.

PropertyTypeDescription
BankGroupIdGuidA unique bank identifier.
BankGroupNameString (100)The bank name.
UniversalBranchCodeString (10)The universal branch code that can be used to make when requesting a payout.