Welcome to MaxiCash

The MaxiCash Integration Platform enables Merchants to integrate with the MaxiCash platform in order to receive payments through their mobile apps or their websites. The API uses JSON to interact with .Net client or open source platforms like PHP.

In order to receive MaxiCash Payments for your Website or Mobile App, you must be registered on the MaxiCash Platform as a Merchant. Here are the steps to follow

  • Step 1. Download the MaxiCash Mobile App and signup...
  • Step 2. Contact us to upgrade your account to a Merchant Account info@maxicashapp.com
    You will receive a Merchant Form to complete in order to provide your business details and preffered Cashout Wallet or Banking Details.
  • Step 3. Once the paperwork is completed, you will be issued with Live and Sandbox Accounts (MerchantID and MerchantPassword)

The MaxiCash Platform has 2 Currencies, The maxiDollar and the maxiRand. The maxiDollar has a 1 to 1 Exchange Rate to the American USD, and is the mostly used currency by our Merchant Network. Merchants in South Africa use the maxiRand currency which has a 1 to 1 Exchange Rate to the South African ZAR.

Image

MaxiCash URL Endpoints

You can integrate to the MaxiCash API and MaxiCash Gateway using the Endpoints below for Sandbox and Live Accounts.

API Sandbox : https://api-testbed.maxicashapp.com/Merchant/api.asmx

API Live : https://api.maxicashapp.com/Merchant/api.asmx

Gateway Sandbox : https://api-testbed.maxicashapp.com/payentry 

Gateway Live : https://api.maxicashapp.com/payentry

Mobile App vs Website Integrations

The MaxiCash Platform Integration supports 2 integration Models: Mobile Apps (MaxiCash API) and Websites (MaxiCash Gateway)

The MaxiCash Gateway is mainly designed to enable easy and quick Website Integration to the MaxiCash Platform. With the MaxiCash Gateway you can receive payment from MaxiCash Users. The Gateway allows the Merchant to also receive payments from non-MaxiCash users using Credit Cards, Paypal, Pepele Mobile and Others.
The MaxiCash Gateway includes a Donate Button for NGOs and eCommerce Plugins for Wordpress/Woocommerce and Prestashop (1.6 and 1.7)

Image


The MaxiCash API is mainly designed to enable Mobile App and Complex Webiste Integrations. It only enables payments from MaxiCash Users. The MaxiCash Users completes the payment using the MaxiCash Moble App from an In-App Notification or by providing an OTP (One Time Pin) SMS sent to the MaxiCash Mobile Number used at registration.

MaxiCash Gateway

The MaxiCash Gateway enables the Merchant to Collect Payment into their MaxiCash account using multiple payment channels such as Credit Cards, MaxiCash, Paypal, Mobile Money and Mobile Banking.

Image

Integrating to the MaxiCash Gateway can be done with:

  • Form Post
  • Posting to URL with QueryString
  • MaxiCash Donate Button
  • eCommerce Plugin (Wordpress/Woocommerce & Prestashop 1.6/1.7)

Form Post Payment

Post the form with the attributes below using these urls :

  • Sandbox : https://api-testbed.maxicashapp.com/PayEntryPost
  • Live : https://api.maxicashapp.com/PayEntryPost
<form action="https://api.maxicashapp.com/PayEntryPost" method="POST">
    <input type="hidden" name="PayType" value="MaxiCash">
    <input type="hidden" name="Amount" value="{TOTAL_AMOUNT}">
    <input type="hidden" name="Currency" value="MaxiDollar">
    <input type="hidden" name="Telephone" value="{MAXICASH_TELEPHONE_NO}">
    <input type="hidden" name="MerchantID" value="{YOUR_MERCHANT_ID}">
    <input type="hidden" name="MerchantPassword" value="{YOUR_MERCHANT_PASSWORD}">
    <input type="hidden" name="Language" value="En">
    <input type="hidden" name="Reference" value="{REFERENCE_OF_TRANSACTION}">
    <input type="hidden" name="accepturl" value="{SUCCESS_URL}">
    <input type="hidden" name="cancelurl" value="{CANCEL_URL}">
    <input type="hidden" name="declineurl" value="{FAILURE_URL}">
</form>
                                

QueryString URL Payment

Post the form with the attributes below using these urls :

  • Sandbox : https://api-testbed.maxicashapp.com/PayEntry
  • Live : https://api.maxicashapp.com/PayEntry

Attach a Query String to the URL with a Json String for Attribute Data

    https://api.maxicashapp.com/payentry?data={PayType:"MaxiCash",Amount:"{TOTAL_AMOUNT}",Currency:"maxiDollar",Telephone:"{MAXICASH_TELEPHONE_NO}",MerchantID:"{YOUR_MERCHANT_ID}",MerchantPassword:"{YOUR_MERCHANT_PASSWORD}",Language:"fr",Reference:"{REFERENCE_OF_TRANSACTION}",Accepturl:"{SUCCESS_URL}",Cancelurl:"{CANCEL_URL}",Declineurl:"{FAILURE_URL}"}
    
                                

Donate Button for NGOs

Post the form with the attributes below using these urls :

  • Sandbox : https://api-testbed.maxicashapp.com/donationentry
  • Live : https://api.maxicashapp.com/donationentry

Attach a Query String to the URL with a Json String for Attribute Data

Once you signup as an NGO Merchant, you will be provided with a Donate with MaxiCash Button sript to put on your website

Sample Donate Button

                                     
Sample Donate Button Link Code
<a id="mxc00"><script async src="https://api-testbed.maxicashapp.com/mxcashbtn.js"></script> </a>
                                    
Direct Donate Code
https://api.maxicashapp.com/donationentry?data={MerchantID:"{YOUR_MERCHANT_ID}",Language:"fr"}

MaxiCash API

The MaxiCash API enables the Merchant to Collect Payment into their MaxiCash account from a MaxiCash User .

Integrating to the MaxiCash API can be done with any of these options:

  • Pay OTP (One Time Pin) SMS
  • Pay In-App Payment Request (Synchronious)
  • Pay In-App Payment Request (Asynchronious)

Pay OTP (One Time Pin) SMS

This payment method is perfect for Mobile App Integration and is done in two steps

  • Step 1 - Initiate the Payment with the PayLaterSynch Method
  • Step 2 - Complete the Payment with the CompletePayLater Method

To integrate with mobile apps, you will need to use the PayLaterSynch method to begin and the CompletePayLater to finalize the payment. When the PayLaterSynch is successful, the user will receive a transaction PIN by SMS that he will need to give you in order to finalize the payment.

PayLaterSynch

The PayLaterSynch method is used to initiate a payment for mobile apps. The method receives the transaction amount, the payment currency, and the payer MaxiCash phone number. The method returns a confirmation message on whether the call was successful or not and a Payment ID. Please note that the payment amounts must be sent in Cents.

CompletePayLater

This method allows you to complete a payment for a mobile app. The method receives a payment ID and a PIN and returns a confirmation of whether the payment was successful or not.

PayLaterSynch - Sample Code
var PmtID = "";
function CallPayLaterSynch() {
    var a = new Object();
    a.Amount = 1000; //please note that the amounts must be sent in Cents
    a.Currency = 'maxiDollar'; //values can be “maxiDollar” or “maxiRand”
    a.Telephone = '{MAXICASH_TELEPHONE_NO}';
    a.MerchantID = '{YOUR_MERCHANT_ID}';
    a.MerchantPassword = '{YOUR_MERCHANT_PASSWORD}';
    a.Language = 'en'; //en or fr
    a.Reference = '{REFERENCE_OF_TRANSACTION}';

    var payloadString = "";
    payloadString = JSON.stringify(a);
    payloadString = payloadString.replace(/\"/g, '\\"');
    var vURL = "https://api-testbed.maxicashapp.com/Merchant/api.asmx/PayLaterSynch";

    $.ajax({
        type: "POST",
        url: vURL,
        data: '{strData: "' + payloadString + '" }',
        contentType: "application/json; charset=utf-8",
        success: function(data) {
            var parsedResponse = typeof data.d == "string" ? eval("(" + data.d + ")") : data.d;
            if (parsedResponse[1] === "Success") {
                alert("An SMS has been sent to your MaxiCash number to finalize the payment");
                PmtID = parsedResponse[3];
            } else {
                alert("An error has occured: " + parsedResponse[2]);
            }
        },
        failure: function(e, textStatus, errorThrown) {
            alert("An error has occured: " + textStatus);
        }
    });
}

 


                                
CompletePayLater - Sample Code
function CallValidatePayment(pin, PmtID) {
    var a = new Object();
    
    a.PaymentID = PmtID; //Received from PayLaterSynch
    a.PIN = pin; //Received from the User
    a.MerchantID = '{YOUR_MERCHANT_ID}';
    a.MerchantPassword = '{YOUR_MERCHANT_PASSWORD}';
    a.Language = 'en'; //en or fr

    var payloadString = "";
    payloadString = JSON.stringify(a);
    payloadString = payloadString.replace(/\"/g, '\\"');
    var vURL = "https://api-testbed.maxicashapp.com/Merchant/api.asmx/CompletePayLater";

    $.ajax({
        type: "POST",
        url: vURL,
        data: '{strData: "' + payloadString + '" }',
        contentType: "application/json; charset=utf-8",
        success: function(data) {
            var parsedResponse = typeof data.d == "string" ? eval("(" + data.d + ")") : data.d;
            if (parsedResponse[1] === "Success") {
                alert("Your payment has been finalized");
            } else {
                alert("An error has occured: " + parsedResponse[2]);
            }
        },
        failure: function(e, textStatus, errorThrown) {
            alert("An error has occured: " + textStatus);
        }
    });
}

 


                                

Pay In-App Payment Synchronious

PayNowSynch

This method is used to process a Synchronous MaxiCash payment from a web site. The method receives a currency, an amount, a telephone number (MaxiCash), a payment method, a reference and the language.

  • Initiate the Payment with the PayNowSynch Method and wait for payment status
  • The User will receive an In-App Notification in the MaxiCash Mobile App, and has 60 seconds to Approve the Payment.
  • During a synchronous payment, the API waits for up to 60 seconds before the transaction times out.

PayNowSynch - Sample Code
function CallPayNowSynch() {
    var a = new Object();
    
    a.PayType = 'MaxiCash';                                
    a.Amount = 1000; //please note that the amounts must be sent in Cents
    a.Currency = 'maxiDollar'; //values can be “maxiDollar” or “maxiRand”
    a.Telephone = '{MAXICASH_TELEPHONE_NO}';
    a.MerchantID = '{YOUR_MERCHANT_ID}';
    a.MerchantPassword = '{YOUR_MERCHANT_PASSWORD}';
    a.Language = 'en'; //en or fr
    a.Reference = '{REFERENCE_OF_TRANSACTION}';

    var payloadString = "";
    payloadString = JSON.stringify(a);
    payloadString = payloadString.replace(/\"/g, '\\"');
    var vURL = "https://api-testbed.maxicashapp.com/Merchant/api.asmx/PayNowSynch";

    $.ajax({
        type: "POST",
        url: vURL,
        data: '{strData: "' + payloadString + '" }',
        contentType: "application/json; charset=utf-8",
        success: function(data) {
            var parsedResponse = typeof data.d == "string" ? eval("(" + data.d + ")") : data.d;
            if (parsedResponse[1] === "Success") {
                alert("Your payment was successful");
            } else {
                alert("An error has occured: " + parsedResponse[2]);
            }
        },
        failure: function(e, textStatus, errorThrown) {
            alert("An error has occured: " + textStatus);
        }
    });
}

Pay In-App Payment Asynchronious

This payment method is perfect for Website with Custom Interfaces not requiring a 60 Second Synchronious process and is done in two steps

  • Step 1 - Initiate an Asychronious MaxiCash Payment Request with the PayNowAsynch Method
  • Step 2 - Check the Status of the Payment by pinging the PayNowStatus Method at regular intervals.

If you use the PayAsynch method, you will need to use the PayNowStatus method to verify whether the user has completed his transaction or not. Please provide an appropriate screen while your website checks for the transaction status.

PayNowAsynch

This method is used to process an Asynchronous MaxiCash payment from a Web site or Mobile App. The method receives a currency, an amount, a telephone number (MaxiCash), a payment method, a reference and the language. The method returns a success status and a Payment ID to enable you to verify the progress of the transaction. We recommend using this method only if you do not want to use the MaxiCash Gateway and want to display a custom interface to your customers. Please note that for all currencies except ‘FC’ receive the amounts in Cents.

PayNowStatus

This method is used to verify the status of a Synchronous MaxiCash or Pepele Mobile payment on a web site. The method receives a payment method, a payment ID and the language (optional). The method returns the merchant success or failure URL depending on whether the user has successfully completed the payment or not.

PayNowAsynch - Sample Code
var PmtID = "";
var PType = "";
function CallPayNowAsynch() {
    var a = new Object();
    a.PayType = 'MaxiCash';
    a.Amount = 1000; //please note that the amounts must be sent in Cents
    a.Currency = 'maxiDollar'; //values can be “maxiDollar” or “maxiRand”
    a.Telephone = '{MAXICASH_TELEPHONE_NO}';
    a.MerchantID = '{YOUR_MERCHANT_ID}';
    a.MerchantPassword = '{YOUR_MERCHANT_PASSWORD}';
    a.Language = 'en'; //en or fr
    a.Reference = '{REFERENCE_OF_TRANSACTION}';

    var payloadString = "";
    payloadString = JSON.stringify(a);
    payloadString = payloadString.replace(/\"/g, '\\"');
    var vURL = "https://api-testbed.maxicashapp.com/Merchant/api.asmx/PayNowAsynch";

    $.ajax({
        type: "POST",
        url: vURL,
        data: '{strData: "' + payloadString + '" }',
        contentType: "application/json; charset=utf-8",
        success: function(data) {
            var parsedResponse = typeof data.d == "string" ? eval("(" + data.d + ")") : data.d;
            if (parsedResponse[1] === "Success") {
                alert("Your payment was initialized. Please complete it on your Mobile device");
                PmtID = parsedResponse[3];
                PType = parsedResponse[6];

            } else {
                alert("An error has occured: " + parsedResponse[2]);
            }
        },
        failure: function(e, textStatus, errorThrown) {
            alert("An error has occured: " + textStatus);
        }
    });
}

                                
PayNowStatus - Sample Code
function CallPayNowStatus(Pmt, PmtType) {
    var a = new Object();
    
    a.PmtID = Pmt;
    a.PType = PmtType;
    a.MerchantID = '{YOUR_MERCHANT_ID}';
    a.MerchantPassword = '{YOUR_MERCHANT_PASSWORD}';
    a.Language = 'en'; //en or fr

    var payloadString = "";
    payloadString = JSON.stringify(a);
    payloadString = payloadString.replace(/\"/g, '\\"');
    var vURL = "https://api-testbed.maxicashapp.com/Merchant/api.asmx/CompletePayLater";

    $.ajax({
        type: "POST",
        url: vURL,
        data: '{strData: "' + payloadString + '" }',
        contentType: "application/json; charset=utf-8",
        success: function(data) {
            var parsedResponse = typeof data.d == "string" ? eval("(" + data.d + ")") : data.d;
            if (parsedResponse[1] === "Success") {
                //redirecting the user to the correct URL
                window.location.href = parsedResponse[4];
                PmtID = parsedResponse[3];

            } else {
                alert("An error has occured: " + parsedResponse[2]);
            }
        },
        failure: function(e, textStatus, errorThrown) {
            alert("An error has occured: " + textStatus);
        }
    });
}

 


                                

MaxiCash eCommerce Modules/Plugins

MaxiCash provides eCommerce Plugins to ease integration to the Platform. Below is the list of available plugins.

  • Magento
  • Prestashop 1.6
  • Prestashop 1.7
  • WordPress/WooCommerce

Please contact us at info@maxicashapp.com to get these plugins setup on your website.