Create User (Wallet)

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

Create a new basic wallet in the specified community. Only Username & MSISDN is required. If this wallet already exists elsewhere on the platform, it will implicitly be added to your community. You can identify which action took place via the returned 'Action' field. It will either be 'Created user' or 'Added user to community'. If the user already exists in your community, you will receive an error, '-1,User already exists in community […]'.

Once complete, you have authorization to perform your whitelisted actions on this wallet, such as /createVoucher.

Request
Response

Parameters

Field	Type	Requirement	Description
`Username`	String	Required	A unique username that acts as your user’s identifier.
`MSISDN`	String	Required	The cell number where your user can receive SMS communication.
`IDNumber`	String	Optional	The ID number of the user. If supplied, it must be unique in your community.
`Password`	String	Optional	The user’s login password. If not provided, user will receive a random 5-digit password.
`Timezone`	String	Optional	The user’s local timezone for accurate date and time display.
`Currency`	String	Optional	The default currency of the user. Default is ZAR.
`ProfileImageUrl`	String	Optional	A URL pointing to the user’s profile picture.
`BannerImageUrl`	String	Optional	A URL for the user’s profile banner or cover image.
`DisplayName`	String	Optional	The display name of the user. If left empty, will be populated with the Username.
`FirstName`	String	Optional	The first name of the user.
`LastName`	String	Optional	The last name of the user.
`Email`	String	Optional	The email address associated with the user.
`HouseNumber`	String	Optional	The house number of the user’s residential address.
`StreetName`	String	Optional	The street name of the user’s residential address.
`Suburb`	String	Optional	The suburb of the user’s residential address.
`Town`	String	Optional	The town of the user’s residential address.
`Province`	String	Optional	The province of the user’s residential address.
`AccountName`	String	Optional	The account name of the user’s bank account.
`AccountNumber`	String	Optional	The account number of the user’s bank account.
`AccountType`	String	Optional	The account type of the user’s bank account.
`BankName`	String	Optional	The name of the user’s bank.
`BranchCode`	String	Optional	The branch code of the user’s bank.
`LowBalanceAlertAmount`	String	Optional	Threshold in cents to trigger a low balance notification.
`TaxNumber`	String	Optional	The tax number of the merchant’s enterprise.
`UMetadata`	String	Optional	Any other detail that you would like to store on this user.
`Metadata`	String	Optional	Any other detail that the merchant wishes to store on this transaction.

Example Body

{
  "Username": "27820000000",
  "MSISDN": "27820000000",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27820000000.jpg",
  "BannerImageUrl": "https://example.com/banner/27820000000.jpg",
  "DisplayName": "John A",
  "FirstName": "John",
  "LastName": "Dory",
  "Email": "john@celbux.com",
  "HouseNumber": "2009",
  "StreetName": "Maritime Street",
  "Suburb": "Centurion",
  "Town": "Pretoria",
  "Province": "Gauteng",
  "AccountName": "MR J DORY",
  "AccountNumber": "6287805043",
  "AccountType": "Savings",
  "BankName": "FNB",
  "BranchCode": "250655",
  "LowBalanceAlertAmount": "10000",
  "TaxNumber": "0777885252",
  "UMetadata": "{\"Sender\":\"John D\"}",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}

Parameters

Field	Type	Description
`TID`	String	The unique ID for this transaction.
`Action`	String	The action that took place, either ‘Created user’ or ‘Added user to community’.
`State`	String	Transaction state (`Success` or `Failed`).
`Status`	String	Transaction status code. `1` for success.
`Error`	String	Failure reason if applicable as noted.

Example Body

{
    "TID": "14975698682",
    "Action": "Created user",
    "State": "Success",
    "Status": "1",
    "Error": ""
}

curl -X POST '{api-url}/createWallet?ns={community}' \
-H 'Authorization: bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"Username":"27820000000","MSISDN":"27820000000","IDNumber":"0108256028085","Password":"P@ssw0rd123","Timezone":"Africa/Johannesburg","Currency":"ZAR","ProfileImageUrl":"https://example.com/profile/27820000000.jpg","BannerImageUrl":"https://example.com/banner/27820000000.jpg","DisplayName":"John A","FirstName":"John","LastName":"Dory","Email":"john@celbux.com","HouseNumber":"2009","StreetName":"Maritime Street","Suburb":"Centurion","Town":"Pretoria","Province":"Gauteng","AccountName":"MR J DORY","AccountNumber":"6287805043","AccountType":"Savings","BankName":"FNB","BranchCode":"250655","LowBalanceAlertAmount":"10000","TaxNumber":"0777885252","UMetadata":"{\"Sender\":\"John D\"}","Metadata":"{\"ActorUserIDs\": \"547828938941114\"}"}'

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

        var jsonPayload = @"{
  ""Username"": ""27820000000"",
  ""MSISDN"": ""27820000000"",
  ""IDNumber"": ""0108256028085"",
  ""Password"": ""P@ssw0rd123"",
  ""Timezone"": ""Africa/Johannesburg"",
  ""Currency"": ""ZAR"",
  ""ProfileImageUrl"": ""https://example.com/profile/27820000000.jpg"",
  ""BannerImageUrl"": ""https://example.com/banner/27820000000.jpg"",
  ""DisplayName"": ""John A"",
  ""FirstName"": ""John"",
  ""LastName"": ""Dory"",
  ""Email"": ""john@celbux.com"",
  ""HouseNumber"": ""2009"",
  ""StreetName"": ""Maritime Street"",
  ""Suburb"": ""Centurion"",
  ""Town"": ""Pretoria"",
  ""Province"": ""Gauteng"",
  ""AccountName"": ""MR J DORY"",
  ""AccountNumber"": ""6287805043"",
  ""AccountType"": ""Savings"",
  ""BankName"": ""FNB"",
  ""BranchCode"": ""250655"",
  ""LowBalanceAlertAmount"": ""10000"",
  ""TaxNumber"": ""0777885252"",
  ""UMetadata"": ""{\""Sender\"":\""John D\""}"",
  ""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);
    }
}

package main

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

func main() {
  url := "{api-url}/createWallet?ns={community}"
  payload := strings.NewReader(`{"Username":"27820000000","MSISDN":"27820000000","IDNumber":"0108256028085","Password":"P@ssw0rd123","Timezone":"Africa/Johannesburg","Currency":"ZAR","ProfileImageUrl":"https://example.com/profile/27820000000.jpg","BannerImageUrl":"https://example.com/banner/27820000000.jpg","DisplayName":"John A","FirstName":"John","LastName":"Dory","Email":"john@celbux.com","HouseNumber":"2009","StreetName":"Maritime Street","Suburb":"Centurion","Town":"Pretoria","Province":"Gauteng","AccountName":"MR J DORY","AccountNumber":"6287805043","AccountType":"Savings","BankName":"FNB","BranchCode":"250655","LowBalanceAlertAmount":"10000","TaxNumber":"0777885252","UMetadata":"{\"Sender\":\"John D\"}","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))
}

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": "27820000000",
  "MSISDN": "27820000000",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27820000000.jpg",
  "BannerImageUrl": "https://example.com/banner/27820000000.jpg",
  "DisplayName": "John A",
  "FirstName": "John",
  "LastName": "Dory",
  "Email": "john@celbux.com",
  "HouseNumber": "2009",
  "StreetName": "Maritime Street",
  "Suburb": "Centurion",
  "Town": "Pretoria",
  "Province": "Gauteng",
  "AccountName": "MR J DORY",
  "AccountNumber": "6287805043",
  "AccountType": "Savings",
  "BankName": "FNB",
  "BranchCode": "250655",
  "LowBalanceAlertAmount": "10000",
  "TaxNumber": "0777885252",
  "UMetadata": "{\"Sender\":\"John D\"}",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}
                """;

        var request = HttpRequest.newBuilder()
                .uri(URI.create("{api-url}/createWallet?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}/createWallet?ns={community}';
    const payload = {
    "Username": "27820000000",
    "MSISDN": "27820000000",
    "IDNumber": "0108256028085",
    "Password": "P@ssw0rd123",
    "Timezone": "Africa/Johannesburg",
    "Currency": "ZAR",
    "ProfileImageUrl": "https://example.com/profile/27820000000.jpg",
    "BannerImageUrl": "https://example.com/banner/27820000000.jpg",
    "DisplayName": "John A",
    "FirstName": "John",
    "LastName": "Dory",
    "Email": "john@celbux.com",
    "HouseNumber": "2009",
    "StreetName": "Maritime Street",
    "Suburb": "Centurion",
    "Town": "Pretoria",
    "Province": "Gauteng",
    "AccountName": "MR J DORY",
    "AccountNumber": "6287805043",
    "AccountType": "Savings",
    "BankName": "FNB",
    "BranchCode": "250655",
    "LowBalanceAlertAmount": "10000",
    "TaxNumber": "0777885252",
    "UMetadata": "{\"Sender\":\"John D\"}",
    "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
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{api-url}/createWallet?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": "27820000000",
  "MSISDN": "27820000000",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27820000000.jpg",
  "BannerImageUrl": "https://example.com/banner/27820000000.jpg",
  "DisplayName": "John A",
  "FirstName": "John",
  "LastName": "Dory",
  "Email": "john@celbux.com",
  "HouseNumber": "2009",
  "StreetName": "Maritime Street",
  "Suburb": "Centurion",
  "Town": "Pretoria",
  "Province": "Gauteng",
  "AccountName": "MR J DORY",
  "AccountNumber": "6287805043",
  "AccountType": "Savings",
  "BankName": "FNB",
  "BranchCode": "250655",
  "LowBalanceAlertAmount": "10000",
  "TaxNumber": "0777885252",
  "UMetadata": "{\"Sender\":\"John D\"}",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}',
  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}/createWallet?ns={community}"
payload = {
  "Username": "27820000000",
  "MSISDN": "27820000000",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27820000000.jpg",
  "BannerImageUrl": "https://example.com/banner/27820000000.jpg",
  "DisplayName": "John A",
  "FirstName": "John",
  "LastName": "Dory",
  "Email": "john@celbux.com",
  "HouseNumber": "2009",
  "StreetName": "Maritime Street",
  "Suburb": "Centurion",
  "Town": "Pretoria",
  "Province": "Gauteng",
  "AccountName": "MR J DORY",
  "AccountNumber": "6287805043",
  "AccountType": "Savings",
  "BankName": "FNB",
  "BranchCode": "250655",
  "LowBalanceAlertAmount": "10000",
  "TaxNumber": "0777885252",
  "UMetadata": "{\"Sender\":\"John D\"}",
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
}

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}/createWallet?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": "27820000000",
  "MSISDN": "27820000000",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27820000000.jpg",
  "BannerImageUrl": "https://example.com/banner/27820000000.jpg",
  "DisplayName": "John A",
  "FirstName": "John",
  "LastName": "Dory",
  "Email": "john@celbux.com",
  "HouseNumber": "2009",
  "StreetName": "Maritime Street",
  "Suburb": "Centurion",
  "Town": "Pretoria",
  "Province": "Gauteng",
  "AccountName": "MR J DORY",
  "AccountNumber": "6287805043",
  "AccountType": "Savings",
  "BankName": "FNB",
  "BranchCode": "250655",
  "LowBalanceAlertAmount": "10000",
  "TaxNumber": "0777885252",
  "UMetadata": "{\"Sender\":\"John D\"}",
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
})

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