Submit refund

POST /secure/refunds/submit

Try it

Bodyapplication/json

[
  {
    "transactionId": "00000000-0000-0000-0000-000000000000",
    "amount": 20.44,
    "refundReason": "<refundReason>",
    "notifyUrl": "https://example.com/notifyurl",
    "hashCheck": "<hashCheck>",
    "isRtc": false
  }
]

[
  {
    "transactionId": "00000000-0000-0000-0000-000000000000",
    "amount": 20.44,
    "refundReason": "<refundReason>",
    "notifyUrl": "https://example.com/notifyurl",
    "hashCheck": "<hashCheck>",
    "isRtc": false
  }
]

Request sampleLanguage

curl -X POST 'https://api.ozow.com/secure/refunds/submit' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "transactionId": "00000000-0000-0000-0000-000000000000",
    "amount": 20.44,
    "refundReason": "<refundReason>",
    "notifyUrl": "https://example.com/notifyurl",
    "hashCheck": "<hashCheck>",
    "isRtc": false
  }
]'

Response exampleStatus

{
  "refundId": "00000000-0000-0000-0000-000000000000",
  "transactionId": "00000000-0000-0000-0000-000000000000",
  "refundAmount": "<refundAmount>",
  "errors": [
    "<errors>"
  ]
}

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

POSThttps://api.ozow.com/secure/refunds/submitProduction

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.

Migrate refunds from the Payments API to One APIEverything needed to move an existing refunds integration onto One API, with the legacy guide and its One API counterpart side by side.
View package

Submit refunds to Ozow for processing.

Authentication

Bearer token
The token generated by the Get API token operation. The same token is used for every request until it expires.

Request body

An array of refund requests.

application/json

array of RefundRequest

application/x-www-form-urlencoded

transactionId string uuid required
The transaction identifier. This is the identifier for the payment that was originally processed on Ozow.
amount number double required
The amount that needs to be refunded. This can be less than the original transaction amount but not more.
refundReason string
The reason for the refund.
max length500
notifyUrl string uri
The URL Ozow will send a notification to once the refund has been finalised.
max length500
hashCheck string required
SHA512 hash proving the request has not been altered after you generated it. Concatenate four fields in this order, with no separator, then append your private key:
1. transactionId
2. amount, formatted with two decimal places, so 100.00
3. refundReason
4. notifyUrl
Hash the result with SHA512 and send the digest as lowercase hexadecimal.

Unlike the payment request hash, do not convert the concatenated string to lowercase before hashing. Refunds hash the string exactly as you built it, so the case of your reason and your notify URL matters. Only the digest is compared case insensitively.
max length150
isRtc boolean
Whether the refund should be processed as an RTC refund.
defaultfalse

Responses

200 OK

application/json

refundId string uuid required
The identifier for the refund that was created. No identifier is returned if there was an error creating the refunds.
transactionId string uuid required
The transaction identifier. This will correspond to one of the transaction identifiers passed through in the request.
refundAmount string required
The refund amount.
errors array of string
Validation errors for the specific refund.

application/xml

refundId string uuid required
The identifier for the refund that was created. No identifier is returned if there was an error creating the refunds.
transactionId string uuid required
The transaction identifier. This will correspond to one of the transaction identifiers passed through in the request.
refundAmount string required
The refund amount.
errors array of string
Validation errors for the specific refund.

Guides

Refund a paymentIssue a refund on the Payments API, the legacy path. Refunds are merchant-initiated backend operations, funded from your float balance.

Request

curl -X POST 'https://api.ozow.com/secure/refunds/submit' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "transactionId": "00000000-0000-0000-0000-000000000000",
    "amount": 20.44,
    "refundReason": "<refundReason>",
    "notifyUrl": "https://example.com/notifyurl",
    "hashCheck": "<hashCheck>",
    "isRtc": false
  }
]'

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.ozow.com/secure/refunds/submit");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");

request.Content = new StringContent(@"[
  {
    ""transactionId"": ""00000000-0000-0000-0000-000000000000"",
    ""amount"": 20.44,
    ""refundReason"": ""<refundReason>"",
    ""notifyUrl"": ""https://example.com/notifyurl"",
    ""hashCheck"": ""<hashCheck>"",
    ""isRtc"": false
  }
]", 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://api.ozow.com/secure/refunds/submit',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_ACCESS_TOKEN',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
[
  {
    "transactionId": "00000000-0000-0000-0000-000000000000",
    "amount": 20.44,
    "refundReason": "<refundReason>",
    "notifyUrl": "https://example.com/notifyurl",
    "hashCheck": "<hashCheck>",
    "isRtc": false
  }
]
JSON,
]);

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

const response = await fetch("https://api.ozow.com/secure/refunds/submit", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    {
      "transactionId": "00000000-0000-0000-0000-000000000000",
      "amount": 20.44,
      "refundReason": "<refundReason>",
      "notifyUrl": "https://example.com/notifyurl",
      "hashCheck": "<hashCheck>",
      "isRtc": false
    }
  ]),
});

const data = await response.json();

import requests

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
}

payload = [
    {
        "transactionId": "00000000-0000-0000-0000-000000000000",
        "amount": 20.44,
        "refundReason": "<refundReason>",
        "notifyUrl": "https://example.com/notifyurl",
        "hashCheck": "<hashCheck>",
        "isRtc": False,
    },
]

response = requests.post(
    "https://api.ozow.com/secure/refunds/submit",
    headers=headers,
    json=payload,
)

Response

{
  "refundId": "00000000-0000-0000-0000-000000000000",
  "transactionId": "00000000-0000-0000-0000-000000000000",
  "refundAmount": "<refundAmount>",
  "errors": [
    "<errors>"
  ]
}

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

Bad Request. The operation could not be carried out. The body is a message rather than a structured error.

There was an error processing your request

Unauthorized. The `ApiKey` header is missing or does not match the site, or for a `Secure` operation the bearer token is missing, expired or invalid.

API key is missing or invalid.