Ozow - Refund API Guide

Get Started

The Ozow Refund API allows you to instruct us to refund any EFT payments that were paid using Ozow.

Before getting started you require the following:

Your Ozow merchant details:
- Site code
- Private key
- API key
Refunds have been enabled for all sites you want to do refunds for

Refund Float

Ozow uses the funds you have loaded into your Ozow float to make refund payments.

Overview

The diagram below outlines the process flow that a standard refund will follow. These steps are explained in detail in the next few sections of this guide.

Get Token

Submit Refunds

Refund Processing

Outcome

List Refunds

API Endpoints

Staging	https://stagingapi.ozow.com
Live	https://api.ozow.com

Common Headers

All requests excluding the "Get Token" request require the following HTTP headers.

Name	Type	Req	Description
Authorization	string (500)	Y	The token generated using the get token method. eg. Authorization: Bearer [token]
Content-Type	string(50)	N	The format the response should be returned in e.g. Accept: application/json Accept: application/x-www-form-urlencoded
Accept	string(50)	Y	The format the response should be returned in e.g. Accept: application/json Accept: application/xml

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

Url /token

Method POST

Headers

Name	Type	Req	Description
ApiKey	string (50)	Y	Your merchant API key
Accept	string(50)	Y	The format the response should be returned in e.g. Accept: application/json Accept: application/xml

URL Params N/A

Data Params

Name	Type	Req	Description
grant_type	string (50)	Y	Set as "password"
SiteCode	string (50)	Y	The i-Pay site code for the site which the payment is being made to

Response Object

Name	Type	Description
access_token	string (500)	The token needed for subsequent requests
token_type	string (50)	The token type
expires_in	string (50)	The lifetime of the token in seconds

Request Example

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

Response Example

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

Submit Refunds

You will pass all refunds you want to be processed in this request.

Url /secure/refunds/submit

Method POST

Headers See common headers

URL Params N/A

Data Params

Type	Description
RefundRequest[]	The refunds to process.

RefundRequest Object

Name	Type	Req	Description
transactionId	guid	Y	The transaction identifier. This is the identifier for the payment that was originally processed on Ozow.
amount	decimal	Y	The amount that needs to be refunded. This can be less than the original transaction amount but not more.
refundReason	string (500)	N	The reason for the refund.
notifyUrl	string (500)	N	The URL Ozow will send a notification to once the refund has been finalised.
hashCheck	string (150)	Y	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 below for more details on how to generate the hash.

Response Object

Name	Type	Description
refundId	guid	The identifier for the refund that was created. No identifier is returned if there was an error creating the refunds.
transactionId	guid	The transaction identifier. This will correspond to one of the transaction identifiers passed through in the request.
refundAmount	decimal	The refund amount.
errors	string[]	Validation errors for the specific refund.

Request Example

POST https://api.ozow.com/secure/refunds/submit HTTP/1.1
Authorization: Bearer J4lnLIZtJSc0Rf...Zunskttzl3MdGEMIDArZ4Yp6QTw6_Z4uDkAJN8Y
Accept: application/json
Content-Type: application/json
[
   {
      "TransactionId":"25716f65-7685-4cce-b3e2-60478490c0dc",
      "Amount":0.01,
      "RefundReason":"Test 1",
      "NotifyUrl":"http://xgfg26qcbpbx.runscope.net",
      "HashCheck":"c588fcb20f32e28d516922d95ada0afd37f...c9b9b7f49a2f26e07be6a23093b11c0bd3a51ef"
   },
   {
      "TransactionId":"e5782b5f-ebed-4ff9-a48b-f8522d6823dd",
      "Amount":0.01,
      "RefundReason":"Test 2",
      "NotifyUrl":"http://xgfg26qcbpbx.runscope.net",
      "HashCheck":"a5bd6db5ce674a5f50b355d7956f2d32ef...fc6c86c1ad66ddeb08cf1930cf7c420432a46725"
   },
   {
      "TransactionId":"67643c93-a139-4b8e-a706-73a5ca108d6c",
      "Amount":1,
      "RefundReason":"Test 3",
      "NotifyUrl":"http://xgfg26qcbpbx.runscope.net",
      "HashCheck":"d38197fe6b1856035859d8a1428b5477...848c95479e6e9a8ce1063b04785463b70ab79329c6"
   }
]

Response Example

[
   {
      "refundId":"9699506a-f6b2-4252-b5cd-24583c614ba0",
      "transactionId":"25716f65-7685-4cce-b3e2-60478490c0dc",
      "refundAmount":0.01,
      "errors":null
   },
   {
      "refundId":"b152902b-c5d4-45c0-aba0-2cac084b6482",
      "transactionId":"e5782b5f-ebed-4ff9-a48b-f8522d6823dd",
      "refundAmount":0.01,
      "errors":null
   },
   {
      "refundId":null,
      "transactionId":"67643c93-a139-4b8e-a706-73a5ca108d6c",
      "refundAmount":1.0,
      "errors":[
         "Hash check invalid"
      ]
   }
]

Generate Request Hash Check

Follow these steps to generate the hash check:

Concatenate the RefundRequest variables (excluding HashCheck) in the order they appear in the table.
Append your private key to the concatenated string. Your private key can be found in merchant details section of the merchant admin site.
Convert the concatenated string to lowercase.
Generate a SHA512 hash of the lowercase concatenated string.

Hash Example

Here is an example of how a hash would be generated using the steps above and the values below.

TransactionId	25716f65-7685-4cce-b3e2-60478490c0dc
Amount	0.01
RefundReason	Test 1
NotifyUrl	http://xgfg26qcbpbx.runscope.net

25716f65-7685-4cce-b3e2-60478490c0dc0.01Test 1http://xgfg26qcbpbx.runscope.net
25716f65-7685-4cce-b3e2-60478490c0dc0.01Test 1http://xgfg26qcbpbx.runscope.net215114531AFF7134A94C88CEEA48E
25716f65-7685-4cce-b3e2-60478490c0dc0.01test 1http://xgfg26qcbpbx.runscope.net215114531aff7134a94c88ceea48e
c588fcb20f32e28d516922d95ada0afd37f898c45376a8a6a782c0d678a0561d3d2483e879eb9d820e02b5810c9b9b7f49a2f26e07be6a23093b11c0bd3a51ef

Refund Processing

Ozow will process the refunds as soon as possible. Payment will be made into the account from which the orginal EFT payment was made.

Outcome

Once you receive a bank message that contains a transaction status the transaction has been concluded and the status of the payment can be determined. You can trigger the relevant actions on your system based on the payment status received.

Status Types

Pending	The refund request has been submitted and accepted.
Complete	The refund has been paid successfully.
Submitted	The refund has been assigned to a batch and is being processed.
Failed	The refund payment has failed.
Cancelled	The refund has been cancelled before it was submitted.
Returned	The refund payment has been returned because the account that was being refunded no longer exists.

Notification

Once the refund has either failed or been completed, Ozow will send a notification to the URL in the request.

Name	Type	Description
RefundId	guid	The refund identifier.
TransactionId	guid	The transaction identifier of the transaction that is being refunded.
CurrencyCode	string (3)	The refund currency. Will always be the same as the amount in the transaction.
Amount	decimal (9,2)	The refund amount. The amount is in the currency specified by the currency code.
Status	string (50)	The refund status. See possible values.
BankName	string (50)	The name of the bank the refund was paid to.
AccountNumber	string (50)	The masked account number payment was made to.
StatusMessage	string (500)	Message regarding the status of the refund. This field will not always have a value.
Hash	string (150)	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 below for more details on how to validate the response variables using the hash.

Notification Hash Check

Follow these steps to generate the hash check:

Concatenate the notification variables (excluding Hash) in the order they appear in the notification fields table above.
Append your private key to the concatenated string. Your private key can be found in merchant details section of the merchant admin site.
Convert the concatenated string to lowercase.
Generate a SHA512 hash of the lowercase concatenated string.
Compare generated hash to the Hash value received.

List Refunds

The API also has the facility of you to query historical refunds data.

GetRefunds

You can use the API to query your refunds, filtering by date and status (only refunds for the authenticated Merchant Site will be returned)

Url /secure/refunds/getrefunds

Method GET

Headers See common headers

URL Params

Type	Description
RefundDate	The date of the refunds you would like to be returned
Status	The status of the refunds you would like to be returned.

Data Params N/A

Response Object

Name	Type	Description
id	guid	The identifier for the refund.
createdDate	DateTime	The date the refund was created.
createdDateUtc	DateTime	The UTC date the refund was created.
merchantCode	string	Corresponding merchant code of the refund.
siteCode	string	Corresponding site code of the refund.
siteName	string	Corresponding site name of the refund.
bankToName	string	Bank the refund was sent to.
currencyCode	string	Refund currency.
amount	decimal	Refund amount.
statementReference	string	Bank reference of the refund for the payer.
status	string	Refund status.
toAccount	string	Account number refund was sent to.
paymentDate	string	Payment date of the refund.
transactionReference	string	Reference of the transaction which was refunded.
customer	string	Refunded transaction customer.
lastEvent	string	LMost recent log activity of the refund.
refundCompletedDate	string	The date the refund was completed.
createdBy	string	Name of the user who created the refund.

Request Example


    POST https://api.ozow.com/secure/refunds/submit HTTP/1.1
    Authorization: Bearer J4lnLIZtJSc0Rf...Zunskttzl3MdGEMIDArZ4Yp6QTw6_Z4uDkAJN8Y
    Accept: application/json
    Content-Type: application/json
    [
        {
            "refundDate":"2018/02/12",
            "status":"Returned"
        }
    ]

Response Example


    [
        {
            "id": "b2d9ba84-a451-4f03-aae4-8cd3c90154fe",
            "createdDate": "2018-02-12T13:34:19.057",
            "createdDateUtc": "2018-02-12T11:34:19.12",
            "merchantCode": "TestMerch",
            "siteCode": "TSTSTE0001",
            "siteName": "test site",
            "bankToName": "Standard Bank New",
            "currencyCode": "ZAR",
            "amount": 150.05,
            "statementReference": "RF test site",
            "status": "Returned",
            "toAccount": "123456789",
            "paymentDate": null,
            "transactionReference": "TTS12C7D6ac30980e",
            "customer": "Test Customer",
            "lastEvent": null,
            "refundCompletedDate": null,
            "createdBy": "Mitchan Adams"
        },
        {
            "id": "25716f65-7685-4cce-b3e2-60478490c0dc",
            "createdDate": "2018-02-12T13:48:12.541",
            "createdDateUtc": "2018-02-12T11:48:12.541",
            "merchantCode": "TestMerch",
            "siteCode": "TSTSTE0001",
            "siteName": "test site",
            "bankToName": "Standard Bank New",
            "currencyCode": "ZAR",
            "amount": 5000.00,
            "statementReference": "RF test site",
            "status": "Returned",
            "toAccount": "123456789",
            "paymentDate": null,
            "transactionReference": "TTS12C7D6ac30980e",
            "customer": "Test Customer",
            "lastEvent": null,
            "refundCompletedDate":  "2018-02-12T13:48:12.541",
            "createdBy": "Mitchan Adams"
        }
    ]