Skip to content

Create Voucher Type

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

Create a new voucher type to classify and restrict pockets of funds.

Request
Response

Parameters

Field	Type	Requirement	Description
`VoucherType`	String	Required	A unique identifier string for the voucher type.
`Group`	String	Optional	The retailer group to automatically link the voucher type to.
`DisplayName`	String	Optional	A user-facing display name.
`Locked`	String	Optional	If `1`, vouchers created under this type are locked.
`AutoLock`	String	Optional	If `1`, vouchers automatically lock after a transaction.
`VSettle`	String	Optional	If `1`, vouchers regenerate their voucher number after spending.
`VAccumulate`	String	Optional	If `1`, funds accumulate into a single voucher pocket.
`WithdrawFee`	String	Optional	A fixed withdrawal fee in cents.
`TransactionOverrides`	String	Optional	Tilde-separated list of TTs allowed to bypass standard restrictions. `~2~` = `/settleVoucher` settles to cash balance (otherwise regenerates), `~4~` = spend anywhere, `~6~` = allow cash withdrawal, `~26~` = allow transferring to another voucher type.
`IsCard`	String	Optional	A frontend filtering flag. Set to `true` for 1-to-1 card types (e.g., individual gift cards) to hide them from general UI dropdowns and prevent clutter (`true` or `false`).
`VMetadata`	String	Optional	Used for basket restrictions. Use `Contains[A\|\|B]` to require a match, or `Contains![A\|\|B]` to reject specific items passed in a `/pay` payload’s Metadata.
`Metadata`	String	Optional	Any other detail to store with this transaction.

Example Body

{
  "VoucherType": "168Cash",
  "Group": "",
  "DisplayName": "Celbux Cash",
  "Locked": "0",
  "AutoLock": "0",
  "VSettle": "1",
  "VAccumulate": "1",
  "VMetadata": "",
  "ThirdParty": "",
  "PIN": "",
  "WithdrawFee": "1000",
  "TransactionOverrides": "~4~6~26~",
  "IsCard": "false",
  "Metadata": ""
}

Parameters

Field	Type	Description
`TID`	String	TID of the executed operation.
`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": "15000000000",
    "State": "Success",
    "Status": "1",
    "Error": ""
}

curl -X POST '{api-url}/createVoucherType?ns={community}' \
-H 'Authorization: bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"VoucherType":"168Cash","Group":"","DisplayName":"Celbux Cash","Locked":"0","AutoLock":"0","VSettle":"1","VAccumulate":"1","VMetadata":"","ThirdParty":"","PIN":"","WithdrawFee":"1000","TransactionOverrides":"~4~6~26~","IsCard":"false","Metadata":""}'

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}/createVoucherType?ns={community}");
        request.Headers.Add("Authorization", "bearer YOUR_TOKEN");

        var jsonPayload = @"{
  ""VoucherType"": ""168Cash"",
  ""Group"": """",
  ""DisplayName"": ""Celbux Cash"",
  ""Locked"": ""0"",
  ""AutoLock"": ""0"",
  ""VSettle"": ""1"",
  ""VAccumulate"": ""1"",
  ""VMetadata"": """",
  ""ThirdParty"": """",
  ""PIN"": """",
  ""WithdrawFee"": ""1000"",
  ""TransactionOverrides"": ""~4~6~26~"",
  ""IsCard"": ""false"",
  ""Metadata"": """"
}";
        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);
    }
}

package main

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

func main() {
  url := "{api-url}/createVoucherType?ns={community}"
  payload := strings.NewReader(`{"VoucherType":"168Cash","Group":"","DisplayName":"Celbux Cash","Locked":"0","AutoLock":"0","VSettle":"1","VAccumulate":"1","VMetadata":"","ThirdParty":"","PIN":"","WithdrawFee":"1000","TransactionOverrides":"~4~6~26~","IsCard":"false","Metadata":""}`)

  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))
}

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 = """
                {
  "VoucherType": "168Cash",
  "Group": "",
  "DisplayName": "Celbux Cash",
  "Locked": "0",
  "AutoLock": "0",
  "VSettle": "1",
  "VAccumulate": "1",
  "VMetadata": "",
  "ThirdParty": "",
  "PIN": "",
  "WithdrawFee": "1000",
  "TransactionOverrides": "~4~6~26~",
  "IsCard": "false",
  "Metadata": ""
}
                """;

        var request = HttpRequest.newBuilder()
                .uri(URI.create("{api-url}/createVoucherType?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());
    }
}

// Requires Node.js v18+
(async () => {
    const url = '{api-url}/createVoucherType?ns={community}';
    const payload = {
    "VoucherType": "168Cash",
    "Group": "",
    "DisplayName": "Celbux Cash",
    "Locked": "0",
    "AutoLock": "0",
    "VSettle": "1",
    "VAccumulate": "1",
    "VMetadata": "",
    "ThirdParty": "",
    "PIN": "",
    "WithdrawFee": "1000",
    "TransactionOverrides": "~4~6~26~",
    "IsCard": "false",
    "Metadata": ""
};

    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
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{api-url}/createVoucherType?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 => '{
  "VoucherType": "168Cash",
  "Group": "",
  "DisplayName": "Celbux Cash",
  "Locked": "0",
  "AutoLock": "0",
  "VSettle": "1",
  "VAccumulate": "1",
  "VMetadata": "",
  "ThirdParty": "",
  "PIN": "",
  "WithdrawFee": "1000",
  "TransactionOverrides": "~4~6~26~",
  "IsCard": "false",
  "Metadata": ""
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: bearer YOUR_TOKEN',
    'Content-Type: application/json'
  ),
));

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

import requests
import json

url = "{api-url}/createVoucherType?ns={community}"
payload = {
  "VoucherType": "168Cash",
  "Group": "",
  "DisplayName": "Celbux Cash",
  "Locked": "0",
  "AutoLock": "0",
  "VSettle": "1",
  "VAccumulate": "1",
  "VMetadata": "",
  "ThirdParty": "",
  "PIN": "",
  "WithdrawFee": "1000",
  "TransactionOverrides": "~4~6~26~",
  "IsCard": "false",
  "Metadata": ""
}

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

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

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

url = URI("{api-url}/createVoucherType?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({
  "VoucherType": "168Cash",
  "Group": "",
  "DisplayName": "Celbux Cash",
  "Locked": "0",
  "AutoLock": "0",
  "VSettle": "1",
  "VAccumulate": "1",
  "VMetadata": "",
  "ThirdParty": "",
  "PIN": "",
  "WithdrawFee": "1000",
  "TransactionOverrides": "~4~6~26~",
  "IsCard": "false",
  "Metadata": ""
})

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