Settlements API Guide

Get Started

The Ozow Settlement API allows merchants to query settlements paid out to them by Ozow. Settlements only apply to merchants who aggregate payments in Ozow's bank account.

Before getting started you require the following:

Your Ozow merchant details:

• Site code
• Private key
• API key

📘

Sliding Scale Fees

When merchants settle on a daily, weekly, fortnightly or adhoc basis, Ozow will forecast the transaction volume and count for the current month to determine a projected fee rate that will be used to calculate the fees owing at the time of settlement. The volume/count used to calculate the rate is calculated by taking the volume/count up to the settlement date, dividing by the number of days from the beginning of the month till the settlement date and multiplying by the number of days in the month.

Overview

The following elements are used to calculate the settlement amount that is paid to the merchant.

• Transactions - All transactions that have cleared and have not been settled up to the settlement date.
• Refunds - All refunds that have and are currently in progress and that have already been processed.
• Fees - All transaction and refund fees for the transactions and refunds processed in settlement.
• Fee Adjustments - If the merchant is on a daily, weekly, fortnightly or adhoc schedule there is a small possibility that they enter a lower bracket at the end of the month. When this occurs Ozow will add a fee adjustment on the next settlement to refund the merchant for an excess fees that might have been paid. This is only applicable to merchants who are on a sliding scale and where the current month's fees are not based on the previous month's volume.
• Settlement Cost - The cost of processing the settlement which is dependent on the method of settlement

API Endpoints

Common Headers

Get API Token

All requests are authenticated using the token you will receive from this request. The same token can be used for all requests until it expires. The only content type supported by this request is "application/x-www-form-urlencoded".

               
 POST https://api.i-pay.co.za/token HTTP/1.1
 ApiKey: EB5758F2C3B4DF3FF4F2669D5FF5B
 Content-Type: application/x-www-form-urlencoded
 grant_type=password&SiteCode=TSTSTE0001
              
            

               
 {  
    "access_token":"x8EMsgirq_74gw11IY18Ugl...l-FW3vumkyTG0GfXudO9U",
    "token_type":"bearer",
    "expires_in":86399
 }
              
            

Get Settlements

Retrieve the lastest settlements created for the merchant.

               
 GET https://api.ozow.com/secure/settlements HTTP/1.1
 Authorization: Bearer J4lnLIZtJSc0Rf...Zunskttzl3MdGEMIDArZ4Yp6QTw6_Z4uDkAJN8Y
 Accept: application/json
              
            

               
 {
 "settlements":[
    {
       "id":"497ac3ea-730c-457a-82fe-229fe79e5f60",
       "date":"2017-04-19 00:00:00.000",
       "originalAmount":150222.75,
       "originalCurrencyCode":"ZAR",
       "bankReference":"SAY097IM382355",
       "amount":9220.38,
       "currencyCode":"EUR",
       "conversionRate":0.0613781,
       "accountNumber":"1234123400",
       "status":"Pending",
       "createdByUserName":"System",
       "createdDate":"2017-04-21 02:10:12.220",
       "createdDateUtc":"2017-04-21 00:10:12.220"
    }
 ],
 "errors": []
 }
              
            

Get Site Settlements

Retrieve the settlements created for the respective merchant site over a selected period.

               
 GET https://api.ozow.com/secure/settlements/
 getsitesettlements HTTP/1.1
 Authorization: Bearer J4lnLIZtJSc0Rf...Zunskttzl3MdGEMIDArZ4Yp6QTw6_Z4uDkAJN8Y
 Accept: application/json
              
            

               
 [
 {
  "settlementId":008822c6-7145-4242-be9b-6f0219486a20,
  "settlementDate":2022-08-19 00:00:00.000,
  "toReference":"TAD14HA38W0021be53",
  "amount":9220.38,
  "bankReference":"SAY097IM382355",
  "status":1,
  "siteCode":"TSTSTE0001",
  "transactionCreatedDate":"2022-08-19 00:00:00.000",
  "transactionId":"677ac3ea-750c-447a-86fe-449fe79e5f61",
  "transactionReference":"SAY097IM382355",
  },
  {
   "settlementId":008822c6-7145-4242-be9b-6f0219486a20,
   "settlementDate":2022-08-19 00:00:00.000,
   "toReference":"TAD18R84659008822c6",
   "amount":520.50,
   "bankReference":"SAY097IM387859",
   "status":1,
   "siteCode":"TSTSTE0001",
   "transactionCreatedDate":"2022-08-20 00:00:00.000",
   "transactionId":"521c3b04-cc43-4560-a9d2-8u5f368010c3",
   "transactionReference":"SAY097IM382355",
   }
   ]
              
            

Settlement Notification URL

You can request Ozow support to configure a notification URL for your merchant account to get notified about settlements as they get created. A single Settlement Object be posted to this URL with the details of the new settlement.