Create Voucher

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

Issue a voucher to the specified user. The value is sent from your merchant account that is linked via the StoreID. Please note that users can automatically be created via this endpoint, subject to the following rules:

• If the user does not exist, a valid MSISDN must be placed into the Username field of the payload.
• If the user does not exist, they will be created and will receive an SMS with voucher number, voucher balance, new username & password.
• If the user exists in another community, they will automatically be added to ?ns={community} used in the endpoint and will receive an SMS with voucher number & voucher balance.
• If the user exists in the ?ns={community}, they will receive an SMS with voucher number & voucher balance.

Request

Parameters

Field	Type	Requirement	Description
Username	String	Optional**	A unique username of the recipient.
VoucherType	String	Required	A voucher type is a pocket of value that can be controlled with various parameters to control spend & withdrawal behaviour.
Amount	String	Required	Transaction amount in cents (e.g., 2000 for R20.00).
Currency	String	Required	Default is currency of merchant (e.g., ZAR).
StoreID	String	Required	A unique identifier provided to the funder that will act as the source of funds.
Reference	String	Optional*	A unique transaction reference number given by the issuer.
Metadata	String	Optional	Any other detail that the issuer wishes to store on this transaction.

*Reference numbers must be unique on the platform otherwise an error will be returned.

**If Username is not provided, the voucher will be sent to your own funding account that is linked via the StoreID.

Example Body

{
  "Username": "27648302057",
  "VoucherType": "168Cash",
  "Amount": "2000",
  "Currency": "ZAR",
  "StoreID": "Store1",
  "Reference": "101",
  "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.
VoucherNo	String	The voucher number that was sent to the recipient.
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": "14975698673",
  "Reference": "101",
  "Created": "2024/05/11 12:00",
  "Amount": "2000",
  "VoucherNo": "168-78439-48310",
  "State": "Success",
  "Status": "1",
  "Error": ""
}

cURL

curl -X POST '{api-url}/createVoucher?ns={community}' \
-H 'Authorization: bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"Username":"27648302057","VoucherType":"168Cash","Amount":"2000","Currency":"ZAR","StoreID":"Store1","Reference":"101","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}/createVoucher?ns={community}");
        request.Headers.Add("Authorization", "bearer YOUR_TOKEN");

        var jsonPayload = @"{
  ""Username"": ""27648302057"",
  ""VoucherType"": ""168Cash"",
  ""Amount"": ""2000"",
  ""Currency"": ""ZAR"",
  ""StoreID"": ""Store1"",
  ""Reference"": ""101"",
  ""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}/createVoucher?ns={community}"
  payload := strings.NewReader(`{"Username":"27648302057","VoucherType":"168Cash","Amount":"2000","Currency":"ZAR","StoreID":"Store1","Reference":"101","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 = """
                {
  "Username": "27648302057",
  "VoucherType": "168Cash",
  "Amount": "2000",
  "Currency": "ZAR",
  "StoreID": "Store1",
  "Reference": "101",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}
                """;

        var request = HttpRequest.newBuilder()
                .uri(URI.create("{api-url}/createVoucher?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}/createVoucher?ns={community}';
    const payload = {
    "Username": "27648302057",
    "VoucherType": "168Cash",
    "Amount": "2000",
    "Currency": "ZAR",
    "StoreID": "Store1",
    "Reference": "101",
    "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}/createVoucher?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 => '{
  "Username": "27648302057",
  "VoucherType": "168Cash",
  "Amount": "2000",
  "Currency": "ZAR",
  "StoreID": "Store1",
  "Reference": "101",
  "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}/createVoucher?ns={community}"
payload = {
  "Username": "27648302057",
  "VoucherType": "168Cash",
  "Amount": "2000",
  "Currency": "ZAR",
  "StoreID": "Store1",
  "Reference": "101",
  "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}/createVoucher?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({
  "Username": "27648302057",
  "VoucherType": "168Cash",
  "Amount": "2000",
  "Currency": "ZAR",
  "StoreID": "Store1",
  "Reference": "101",
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
})

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