Refund (Voucher Number)

POST {api-url}/refund2?ns={community}

Execute a refund transaction based on the voucher number used in the original transaction. You can process multiple partial refunds. Any amount up to the original transaction amount can be entered. Funds are reversed from the merchant’s cash balance, and the commission is returned to the merchant.

If the voucher corresponds to a Voucher Type, the funds returned back to the merchant as the typed voucher. If you would like the funds returned to cash balance, please look at /reverseClosure.

Request

Parameters

Field	Type	Requirement	Description
VoucherNo	String	Required	The voucher number used in the original transaction.
Amount	String	Required	Transaction amount in cents.
StoreID	String	Required	A unique store identifier code for the merchant.
Currency	String	Required	Default is currency of merchant (e.g., ZAR).
Reference	String	Optional*	A unique transaction reference number given by the merchant.
Metadata	String	Optional	Any other detail that the merchant wishes to store on this transaction.

*Reference numbers must be unique identifiers otherwise an error will be returned.

Example Body

{
  "VoucherNo": "168-41405-74358",
  "Amount": "2000",
  "StoreID": "Store1",
  "Reference": "101",
  "Currency": "ZAR",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}

Response

Parameters

Field	Type	Description
TID	String	TID (Transaction ID) of the executed payment response.
Reference	String	The unique transaction reference number from the request.
Created	String	Transaction execution time (YYYY/MM/DD HH:MM).
Amount	String	Transaction amount in cents.
State	String	Transaction state (Success or Failed).
Status	String	Transaction status code (1 or negative error code).
Error	String	Failure reason, if applicable.

Example Body

{
    "TID": "18975693643",
    "Reference": "101",
    "Created": "2024/05/11 12:00",
    "Amount": "2000",
    "State": "Success",
    "Status": "1",
    "Error": ""
}

cURL

curl -X POST '{api-url}/refund2?ns={community}' \
-H 'Authorization: bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"VoucherNo":"168-41405-74358","Amount":"2000","StoreID":"Store1","Reference":"101","Currency":"ZAR","Metadata":"{\"ActorUserIDs\": \"547828938941114\"}"}'

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        var request = new HttpRequestMessage(HttpMethod.Post, "{api-url}/refund2?ns={community}");
        request.Headers.Add("Authorization", "bearer YOUR_TOKEN");

        var jsonPayload = @"{
  ""VoucherNo"": ""168-41405-74358"",
  ""Amount"": ""2000"",
  ""StoreID"": ""Store1"",
  ""Reference"": ""101"",
  ""Currency"": ""ZAR"",
  ""Metadata"": ""{\""ActorUserIDs\"": \""547828938941114\""}""
}";
        request.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

        var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();

        var responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseBody);
    }
}

Go

package main

import (
  "fmt"
  "io/ioutil"
  "net/http"
  "strings"
)

func main() {
  url := "{api-url}/refund2?ns={community}"
  payload := strings.NewReader(`{"VoucherNo":"168-41405-74358","Amount":"2000","StoreID":"Store1","Reference":"101","Currency":"ZAR","Metadata":"{\"ActorUserIDs\": \"547828938941114\"}"}`)

  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Authorization", "bearer YOUR_TOKEN")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()

  body, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(body))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ApiRequest {
    public static void main(String[] args) throws Exception {
        var payload = """
                {
  "VoucherNo": "168-41405-74358",
  "Amount": "2000",
  "StoreID": "Store1",
  "Reference": "101",
  "Currency": "ZAR",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}
                """;

        var request = HttpRequest.newBuilder()
                .uri(URI.create("{api-url}/refund2?ns={community}"))
                .header("Authorization", "bearer YOUR_TOKEN")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Node.js

// Requires Node.js v18+
(async () => {
    const url = '{api-url}/refund2?ns={community}';
    const payload = {
    "VoucherNo": "168-41405-74358",
    "Amount": "2000",
    "StoreID": "Store1",
    "Reference": "101",
    "Currency": "ZAR",
    "Metadata": {
        "ActorUserIDs": "547828938941114"
    }
};

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Authorization': 'bearer YOUR_TOKEN',
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });
        const data = await response.json();
        console.log(data);
    } catch (error) {
        console.error('Error:', error);
    }
})();

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{api-url}/refund2?ns={community}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "VoucherNo": "168-41405-74358",
  "Amount": "2000",
  "StoreID": "Store1",
  "Reference": "101",
  "Currency": "ZAR",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: bearer YOUR_TOKEN',
    'Content-Type: application/json'
  ),
));

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

Python

import requests
import json

url = "{api-url}/refund2?ns={community}"
payload = {
  "VoucherNo": "168-41405-74358",
  "Amount": "2000",
  "StoreID": "Store1",
  "Reference": "101",
  "Currency": "ZAR",
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
}

headers = {
    "Authorization": "bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Ruby

require 'uri'
require 'net/http'
require 'json'

url = URI("{api-url}/refund2?ns={community}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'bearer YOUR_TOKEN'
request["Content-Type"] = 'application/json'

request.body = JSON.dump({
  "VoucherNo": "168-41405-74358",
  "Amount": "2000",
  "StoreID": "Store1",
  "Reference": "101",
  "Currency": "ZAR",
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
})

response = http.request(request)
puts response.read_body