MENU Navbar
javascript php python
  • Welcome
  • Usage

    • Welcome

    Mazzuma provides easy to use interfaces for connecting your web application or mobile application to the service. This allow you to gain mobile money payments from customers and clients with optimal ease and at no extra charges (standard mobile money operator charges apply).

    Usage

    Mazzuma Mobile Money API

    First Steps

    In order to start using Mazzuma to receive payments, you would have to register to use the service. Head over to the dashboard and create a new Mazzuma account. You would enter the mobile money account you would wish payments to be made to during the registration process. Once registered, log into your account. You would have an API key generated, which you can view in the API section. This API Key should be noted, as it would authorise payments to your account, as well as direct incoming funds to your mobile money account.

    Additionally, you must fill out our verification form , as a mandatory check against fraudulent activities.

    Websites and Applications

    Sample Payload

    {
  "price": 1,
  "network": "mtn",
  "recipient_network": "mtn",
  "recipient_number": "23324xxxxxxx",
  "sender": "23324xxxxxxx",
  "option": "rmtm",
  "api_key": "",
  "order_id": ""
}

    Sample Request

      var xhr = new XMLHttpRequest();
  xhr.open("POST", 'https://api.mazzuma.com/v2/money/transfer', true);

  //Send the proper header information along with the request
  xhr.setRequestHeader("Content-type", "application/json");

  xhr.onreadystatechange = function() {
    //Call a function when the state changes.
      if(xhr.readyState == XMLHttpRequest.DONE && xhr.status == 200) {
          // Request finished. Do processing here.
      }
  }
  //Replace requestPayload with the payload you would be sending
  xhr.send(requestPayload); 

    <?php
$url = 'https://api.mazzuma.com/v2/money/transfer';


$additional_headers = array(
   'Content-Type: application/json'
);

$data = array(
  "price"=> 1,
  "network"=> "mtn",
  "recipient_number"=> "026xxxxxxx",
  "sender"=> "024xxxxxxx",
  "option"=> "rmta",
  "api_key"=> ""
  );
$data = json_encode($data);

$ch = curl_init($url);                                                                      
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");                                                                     
curl_setopt($ch, CURLOPT_POSTFIELDS, $data); // $data is the request payload in JSON format                                                                 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);                                                                      
curl_setopt($ch, CURLOPT_HTTPHEADER, $additional_headers); 

$server_output = curl_exec ($ch);
?>

    # Note this sample is functional for python 3 only. 
# It also makes use of the requests library, available at python-requests.org

import requests 

url= 'https://api.mazzuma.com/v2/money/transfer'
payload =  # the payload object for the request
response = requests.post(url, data=payload)

    Making a payment request

    ENDPOINT

    https://api.mazzuma.com/v2/money/transfer

    CONTENT TYPE

    application/json

    REQUEST TYPE

    POST

    PAYLOAD

    Key Description
    price The amount to be paid
    network This is the network of the mobile money account that would be making the payment (your customer).
    recipient_number This is the mobile money account the payments shall end up in. (your account).
    sender This is the mobile money account that would be making the payment (your customers).
    option This denotes the direction of cash flow. For example, rmta can be understood as an acronym of the phrase "receive mtn to airtel", which means you would be receiving money to your Airtel account (the recipient number) from an MTN number(the sender). This format would hold for all transaction requests sent to the API. Do not forget to append the r at beginning.
    api_key The API key generated when you created the Mazzuma Business account. This can be accessed or changed via the web dashboard.
    order_id This optional parameter can be added to track the status of a transaction after it has been completed by use of our check status endpoint. Please note that the order ID is not the same as the transaction ID returned after a transaction request.
    token This is the token generated by Vodafone users in order to complete mobile money payments. This parameter is only required when the payment is to be made by a Vodafone user.

    Response

    Sample Response

    {
  "success": true,
  "message": {
  	"result": 0,
  	"message": {
  		"refNo": "LpwszTxj20220xxxxxxxxx",
  		"status": "SUCCESSFUL",
  		"responseCode": "01", 
  		"responseMessage": "Successfully Processed Transaction|Sending  to 23324xxxxxxx",
  		"networkTransactionId": "17xxxxxxxx",
		"uniwalletTransactionId": "16xxxxxxxxxx",
		"timestamp": "2022-05-24 17:49:00"
	}
  }
}

    Sending the request would bring up a confirmation and payment prompt on the mobile phone, after which the request would return a response. The request to the API would wait until the payment succeeds or fails, and return a JSON response.

    The status denotes whether the transaction was successful or failed, and the id is the transaction ID.

    Network Considerations

    1. Dial *170#
    2. Select option 10) Wallet
    3. Select 3) My Approvals
    4. Enter Mobile Money PIN
    5. Select the transaction from the list
    6. Confirm the transaction.

    Checking a Transaction Status

    Sample Status Check Responses

    {"code":200,"id":"XXXXX","status":"Successful"}
{"code":200,"id":"XXXXX","status":"Failed"}
{"code":200,"id":"XXXXX","status":"Pending"}

    If at any time you wish to check the status of a transaction, you can send a GET request to https://client.teamcyst.com/checktransaction.php?orderID=<id> , with the orderID parameter set to the order ID you sent with the initial transaction request.

    Wordpress Sites

    For WordPress websites which utilise the WooCommerce e-commerce plugin, Mazzuma offers an easy to use plugin that integrates the Mazzuma payment option into the website. Kindly note that you should have completed our general first steps, including filling out our verification form before use of the plugin.

    1. Ensure that the WooCommerce plug-in in already installed and properly set-up on your website.
    2. In your WordPress admin dashboard, search for the 'WooCommerce Mazzuma Payment Gateway' and install the plugin.
    3. Once installed, activate the plugin.
    4. Still in the WordPress admin dashboard, go to the WooCommerce plugin settings, and the Checkout tab.
    5. If the plugin correctly installed, there should be a Mazzuma payment option among the payment gateways listed at the bottom of the page. However, it would not be enabled.
    6. Select the Mazzuma gateway, and you would be taken to the plugin configuration page.
    7. Here, first enable the plugin, and then add the API key generated from the dashboard. Please note payments would not work without this API key. Once done, hit save.
    8. Mazzuma should now be listed as an enabled payment gateway, and your customers would see the option to pay using Mazzuma at checkout pages on your site. Clicking that option should redirect them to the payment page
    9. Once payment is done on the payment page, you would probably want users to be directed to your site. The payment page automatically redirects the user to the URL supplied as the success_url so you might want to use your site URL for that.

    MAZ Token API

    First Steps

    In order to start sending and receiving Mazzuma tokens, you would have to register to use the service. Head over to the website and create a new Mazzuma account. You would enter a unique wallet username you would wish to use during the registration process. Once registered, log into your account. You would have an API key generated, which you can view in the API section. This API Key should be noted, as it would authorise payments in your account.

    Send Mazzuma Tokens

    Sample Request

      var xhr = new XMLHttpRequest();
  xhr.open("POST", 'https://client.teamcyst.com/phase3/mazexchange-api.php', true);
  //Send the proper header information along with the request
  xhr.setRequestHeader("Content-type", "application/json");
  xhr.onreadystatechange = function() {
    //Call a function when the state changes.
      if(xhr.readyState == XMLHttpRequest.DONE && xhr.status == 200) {
          // Request finished. Do processing here.
      }
  }
  //Replace requestPayload with the payload you would be sending
  xhr.send(requestPayload); 

    <?php
$url = 'https://client.teamcyst.com/phase3/mazexchange-api.php';
$additional_headers = array(
   'Content-Type: application/json'
);
$data = array(
  "amount"=> 1,
  "recipient"=> "",
  "sender"=> "",
  "api_key"=> ""
  );
$data = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data); // $data is the request payload in JSON format
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $additional_headers);
$server_output = curl_exec ($ch);
?>

    # Note this sample is functional for python 3 only. 
# It also makes use of the requests library, available at python-requests.org

import requests

url= 'https://client.teamcyst.com/phase3/mazexchange-api.php'
payload =  # the payload object for the request
response = requests.post(url, data=payload)

    REQUEST

    POST https://client.teamcyst.com/phase3/mazexchange-api.php

    CONTENT TYPE

    application/json

    PAYLOAD

    Your payload should be sent in JSON format.

    Key Type Description
    price Number The amount to be sent
    recipient String This is the unique username of the recipient of the transaction.
    sender String This is the unique username of the sender of the transaction.
    api_key String The API key generated when you created the Mazzuma Business account. This can be accessed or changed via the web dashboard.

    SAMPLE RESPONSE

    {"code":1,"status":"success","id":"XXXXX"}

    Receive Mazzuma Tokens

    When receiving MAZ tokens, a notification will be sent to the callbackURL that you set using this API.

    REQUEST

    POST https://client.teamcyst.com/phase3/mazexchange-api.php

    PAYLOAD

    Key Type Description
    api_key String Your account API Key
    option String The option for this request should be set_callback_url
    sender String The account making the payment
    callback_url String Your callback URL

    SAMPLE RESPONSE

    {"code":1,"status":"success"}

    Checking Transaction Status

    REQUEST

    GET https://client.teamcyst.com/checktransaction.php?hash=<TRANSACTION_HASH>

    PAYLOAD

    Your payload should be sent in JSON format.

    Key Type Description
    hash String The hash of the transaction you want to check.

    SAMPLE RESPONSE

    {"code":200,"hash":"d6c002acf0425f3aa5bf6f44543bb99cd137474b","status":"Successful"}

    Get Account Balance

    REQUEST

    POST https://client.teamcyst.com/phase3/mazexchange-api.php

    PAYLOAD

    Key Type Description
    api_key String Your account API Key
    option String The option for this request should be get_balance

    SAMPLE RESPONSE

    {"code":200,"hash":"d6c002acf0425f3aa5bf6f44543bb99cd137474b","status":"Successful"}

    Validate Account

    REQUEST

    POST https://client.teamcyst.com/phase3/mazexchange-api.php

    PAYLOAD

    Key Type Description
    api_key String Your account API Key
    option String The option for this request should be validate_account
    username String The account username you wish to validate

    SAMPLE RESPONSE

    {"code":1,"status":"success","username":"stark","message":"Account is valid"}

    javascript php python