Skip to content

Create User (Merchant)

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

Create a new merchant in the specified community. Only Username & MSISDN is required. This action is implicitly guarded. If a user with the specified details already exists in another community, you will receive an error: '-504,Transaction Field - User cannot be implicitly added to this community'.

Once complete, you have authorization to perform your whitelisted actions on this merchant.

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.
`CanWithdraw`	String	Optional	Specifies if the merchant is permitted to perform a withdrawal with customers (`0` or `1`).
`LowBalanceAlertAmount`	String	Optional	Threshold in cents to trigger a low balance notification.
`Provider`	String	Optional	The merchant provider associated with the merchant’s account.
`Group`	String	Optional	The merchant group associated with the merchant’s account.
`Longitude`	String	Optional	The longitude of the user’s location for mapping services.
`Latitude`	String	Optional	The latitude of the user’s location for mapping services.
`CommercialRegistrationNumber`	String	Optional	The commercial registration number of the merchant’s enterprise.
`TaxNumber`	String	Optional	The tax number of the merchant’s enterprise.
`StoreID`	String	Optional	The globally routed StoreID that is used with transaction APIs.
`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": "merchant_27823334444",
  "MSISDN": "27823334444",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27648302057.jpg",
  "BannerImageUrl": "https://example.com/banner/27648302057.jpg",
  "DisplayName": "SuperMart",
  "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",
  "CanWithdraw": "1",
  "LowBalanceAlertAmount": "10000",
  "Provider": "ParentCompany",
  "Group": "FoodCompanyA",
  "Longitude": "28.2833",
  "Latitude": "-25.7479",
  "CommercialRegistrationNumber": "2012/759414/07",
  "TaxNumber": "0777885252",
  "StoreID": "SM001",
  "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": "14975698681",
    "Action": "Created user",
    "State": "Success",
    "Status": "1",
    "Error": ""
}

curl -X POST '{api-url}/createMerchant?ns={community}' \
-H 'Authorization: bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"Username":"merchant_27823334444","MSISDN":"27823334444","IDNumber":"0108256028085","Password":"P@ssw0rd123","Timezone":"Africa/Johannesburg","Currency":"ZAR","ProfileImageUrl":"https://example.com/profile/27648302057.jpg","BannerImageUrl":"https://example.com/banner/27648302057.jpg","DisplayName":"SuperMart","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","CanWithdraw":"1","LowBalanceAlertAmount":"10000","Provider":"ParentCompany","Group":"FoodCompanyA","Longitude":"28.2833","Latitude":"-25.7479","CommercialRegistrationNumber":"2012/759414/07","TaxNumber":"0777885252","StoreID":"SM001","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}/createMerchant?ns={community}");
        request.Headers.Add("Authorization", "bearer YOUR_TOKEN");

        var jsonPayload = @"{
  ""Username"": ""merchant_27823334444"",
  ""MSISDN"": ""27823334444"",
  ""IDNumber"": ""0108256028085"",
  ""Password"": ""P@ssw0rd123"",
  ""Timezone"": ""Africa/Johannesburg"",
  ""Currency"": ""ZAR"",
  ""ProfileImageUrl"": ""https://example.com/profile/27648302057.jpg"",
  ""BannerImageUrl"": ""https://example.com/banner/27648302057.jpg"",
  ""DisplayName"": ""SuperMart"",
  ""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"",
  ""CanWithdraw"": ""1"",
  ""LowBalanceAlertAmount"": ""10000"",
  ""Provider"": ""ParentCompany"",
  ""Group"": ""FoodCompanyA"",
  ""Longitude"": ""28.2833"",
  ""Latitude"": ""-25.7479"",
  ""CommercialRegistrationNumber"": ""2012/759414/07"",
  ""TaxNumber"": ""0777885252"",
  ""StoreID"": ""SM001"",
  ""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}/createMerchant?ns={community}"
  payload := strings.NewReader(`{"Username":"merchant_27823334444","MSISDN":"27823334444","IDNumber":"0108256028085","Password":"P@ssw0rd123","Timezone":"Africa/Johannesburg","Currency":"ZAR","ProfileImageUrl":"https://example.com/profile/27648302057.jpg","BannerImageUrl":"https://example.com/banner/27648302057.jpg","DisplayName":"SuperMart","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","CanWithdraw":"1","LowBalanceAlertAmount":"10000","Provider":"ParentCompany","Group":"FoodCompanyA","Longitude":"28.2833","Latitude":"-25.7479","CommercialRegistrationNumber":"2012/759414/07","TaxNumber":"0777885252","StoreID":"SM001","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": "merchant_27823334444",
  "MSISDN": "27823334444",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27648302057.jpg",
  "BannerImageUrl": "https://example.com/banner/27648302057.jpg",
  "DisplayName": "SuperMart",
  "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",
  "CanWithdraw": "1",
  "LowBalanceAlertAmount": "10000",
  "Provider": "ParentCompany",
  "Group": "FoodCompanyA",
  "Longitude": "28.2833",
  "Latitude": "-25.7479",
  "CommercialRegistrationNumber": "2012/759414/07",
  "TaxNumber": "0777885252",
  "StoreID": "SM001",
  "UMetadata": "{\"Sender\":\"John D\"}",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}
                """;

        var request = HttpRequest.newBuilder()
                .uri(URI.create("{api-url}/createMerchant?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}/createMerchant?ns={community}';
    const payload = {
    "Username": "merchant_27823334444",
    "MSISDN": "27823334444",
    "IDNumber": "0108256028085",
    "Password": "P@ssw0rd123",
    "Timezone": "Africa/Johannesburg",
    "Currency": "ZAR",
    "ProfileImageUrl": "https://example.com/profile/27648302057.jpg",
    "BannerImageUrl": "https://example.com/banner/27648302057.jpg",
    "DisplayName": "SuperMart",
    "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",
    "CanWithdraw": "1",
    "LowBalanceAlertAmount": "10000",
    "Provider": "ParentCompany",
    "Group": "FoodCompanyA",
    "Longitude": "28.2833",
    "Latitude": "-25.7479",
    "CommercialRegistrationNumber": "2012/759414/07",
    "TaxNumber": "0777885252",
    "StoreID": "SM001",
    "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}/createMerchant?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": "merchant_27823334444",
  "MSISDN": "27823334444",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27648302057.jpg",
  "BannerImageUrl": "https://example.com/banner/27648302057.jpg",
  "DisplayName": "SuperMart",
  "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",
  "CanWithdraw": "1",
  "LowBalanceAlertAmount": "10000",
  "Provider": "ParentCompany",
  "Group": "FoodCompanyA",
  "Longitude": "28.2833",
  "Latitude": "-25.7479",
  "CommercialRegistrationNumber": "2012/759414/07",
  "TaxNumber": "0777885252",
  "StoreID": "SM001",
  "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}/createMerchant?ns={community}"
payload = {
  "Username": "merchant_27823334444",
  "MSISDN": "27823334444",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27648302057.jpg",
  "BannerImageUrl": "https://example.com/banner/27648302057.jpg",
  "DisplayName": "SuperMart",
  "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",
  "CanWithdraw": "1",
  "LowBalanceAlertAmount": "10000",
  "Provider": "ParentCompany",
  "Group": "FoodCompanyA",
  "Longitude": "28.2833",
  "Latitude": "-25.7479",
  "CommercialRegistrationNumber": "2012/759414/07",
  "TaxNumber": "0777885252",
  "StoreID": "SM001",
  "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}/createMerchant?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": "merchant_27823334444",
  "MSISDN": "27823334444",
  "IDNumber": "0108256028085",
  "Password": "P@ssw0rd123",
  "Timezone": "Africa/Johannesburg",
  "Currency": "ZAR",
  "ProfileImageUrl": "https://example.com/profile/27648302057.jpg",
  "BannerImageUrl": "https://example.com/banner/27648302057.jpg",
  "DisplayName": "SuperMart",
  "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",
  "CanWithdraw": "1",
  "LowBalanceAlertAmount": "10000",
  "Provider": "ParentCompany",
  "Group": "FoodCompanyA",
  "Longitude": "28.2833",
  "Latitude": "-25.7479",
  "CommercialRegistrationNumber": "2012/759414/07",
  "TaxNumber": "0777885252",
  "StoreID": "SM001",
  "UMetadata": "{\"Sender\":\"John D\"}",
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
})

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