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
- Dial *170#
- Select option 10) Wallet
- Select 3) My Approvals
- Enter Mobile Money PIN
- Select the transaction from the list
- 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.
- Ensure that the WooCommerce plug-in in already installed and properly set-up on your website.
-
In your WordPress admin dashboard, search for the 'WooCommerce
Mazzuma Payment Gateway' and install the plugin.
- Once installed, activate the plugin.
- Still in the WordPress admin dashboard, go to the WooCommerce plugin settings, and the Checkout tab.
- 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.
- Select the Mazzuma gateway, and you would be taken to the plugin configuration page.
- 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.
- 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
- 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"}