If you’ve been following the tutorials, you’ll remember that in Tutorial 4 we set up our application to send visitors a message each time they connected. We also stored the visitors’ MxitID in a Mongo database connected to our cloud infrastructure on AppFog. The tutorial required connecting to multiple services and getting authorisation from the Mxit Authorisation API. In this tutorial we’ll do something that’s quite a bit easier: get some Moola!
Step 1 - Moola matters
Moola is the virtual currency used within Mxit, and the way users will
pay for items within your app. And thanks to the developers behind the
scenes at Mxit, it couldn’t be easier to call the Billing API. Create a
new file in your testappmxt directory (refer to Tutorial’s 1 and 2 if you need to revise the details) and call it something sensible like billing.php. Don’t forget to make sure that your app info is updated with the new URL on your dashboard like so:
Figure 1: Updating your Mobi Portal URL in the developer dashboard.
Here’s the first section of billing.php:
<?php
$payment_url = 'http://billing.internal.mxit.com/Transaction/PaymentRequest';
/* Set up the transaction */
$VendorId = 1;
$TransactionReference = "Mxit payment";
$CallbackUrl = "http://testappmxt.eu01.aws.af.cm/received.php";
$ProductId = "001";
$ProductName = "Essential service";
$ProductDescription = "An essential service";
$MoolaAmount = "1";
$CurrencyAmount = "-";
The payment URL is the address of Mxit’s internal Billing API. You
won’t be able to test this link in a browser because it’s not visible
to the outside - only running Mxit applications can resolve it
successfully. The next section is the details you need to perform a
transaction. The Vendor ID is set to 1 which is a special test id so
that you can try out the API without draining yourself of real Moola.
The transaction reference is for your own purposes. It must be unique -
you won’t be able to bill the same user for the same transaction twice
otherwise the call will fail. The callback URL is what Mxit will
redirect to once the transaction has been completed. We’ll create that
file in a moment. The rest of the variables are fairly self-descriptive.
The product’s name and description will be presented to the user during
the transaction as well as the Moola amount. The currency amount is
optional and is included to make it clear to the user what the value of
the item he is about to shell out for. The amount does not necessarily
have to correspond with the amount of Moola being charged, and there is
no restriction on the format or currency. I’ve left it blank here.
Step 2 - Building the Billing Query
Now that we’ve set up our transaction, let’s build a useful query out of it.
$params = array( 'VendorId' => $VendorId,'TransactionReference' => $TransactionReference,<
'CallbackUrl' => $CallbackUrl,
'ProductId' => $ProductId,
'ProductName' => $ProductName,
'ProductDescription' => $ProductDescription,
'MoolaAmount' => $MoolaAmount,
'CurrencyAmount' => $CurrencyAmount
);
$url = '<a href="' . $payment_url . "?";
$url = $url . http_build_query($params);
$url = $url . '">' . $MoolaAmount . "</a>" . " Moola";
?>
This is bread and butter PHP: put the variables into an array, create ourselves a url and then build up a link to a properly formatted query with the values. Then we put in the HTML boilerplate and display it all to the page.
<html>And here’s what they’ll see:
<head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="cache-control" content="no-cache">
<meta name="mxit" content="clearscreen,no-prefix,show-progress" /> <title></title>
</head>
<body>
<?php
print "Hi! "; print "Pay me " . $url;
?>
</body>
</html>
Figure 2: Rendering your app within the Mxit environment
Step 3 - Redirections
Remember that you can only follow this link from within Mxit - the Billing URL is not accessible from the outside for security reasons. Start your favourite mobile or desktop client, log in as yourself, add your app as a contact and select the URL from the messaging window. You will see the following screen:
The Billing server is now in control. Sadly I have no more Moola here and will have to top up if I want to buy this Essential Service. But what happens next? This is where our callback URL is used. In billing.php we specified it to be: http://testappmxt.eu01.aws.af.cm/received.php. So let’s create that file and upload it. Here’s what it looks like:
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title></title>
</head>
<body>
<?php
$result = $_GET['mxit_transaction_res'];$message = 'nothing';
if($result ==0)
{
$message = 'Transaction completed successfully.Thank you for the money!';
}
else if($result == 1)
{
$message = 'Transaction rejected.';
}
else if($result == 2)
{
$message = 'Invalid MXit login name or password (authentication failure).';
}
else if($result == 3)
{
$message = 'Your user account is locked.';
}
else if($result == 4)
{
$message = 'You have insufficient funds.';
}
else if($result == 5)
{
$message = 'Transaction timed out before a response was received from the user.';
}
else if($result == 6)
{
$message = 'You logged out without confirming or rejecting the transaction.';
}
else if($result == -2)
{
$message = 'The transaction parameters are not valid';
}
else
{
$message = 'Technical system error occurred.';
}
echo $message;
?>
</body>
</html>
The final code
<?php
$payment_url = 'http://billing.internal.mxit.com/Transaction/PaymentRequest';
/* Set up the transaction */
$VendorId = 1;
$TransactionReference = "Mxit payment";
$CallbackUrl = "http://testappmxt.eu01.aws.af.cm/received.php";
$ProductId = "001";
$ProductName = "Essential service";
$ProductDescription = "An essential service";
$MoolaAmount = "1";
$CurrencyAmount = "-";
$params = array( 'VendorId' => $VendorId,
'TransactionReference' => $TransactionReference,
'CallbackUrl' => $CallbackUrl,
'ProductId' => $ProductId,
'ProductName' => $ProductName,<
'ProductDescription' => $ProductDescription,
'MoolaAmount' => $MoolaAmount,
'CurrencyAmount' => $CurrencyAmount
$url = '<a href="' . $payment_url . "?";
$url = $url . http_build_query($params);
$url = $url . '">' . $MoolaAmount . "</a>" . " Moola";
?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="cache-control" content="no-cache">
<meta name="mxit" content="clearscreen,no-prefix,show-progress" />
<title></title>
</head>
<body>
<?php
print "Hi! ";
print "Pay me " . $url;
?>
</body>
</html>
Final thoughts
As you can see, the Billing API is much simpler than what we’ve done previously. Set up the parameters, call the API and get a result back. But it’s also very robust. When you do a payment request all sorts of checks are done before it goes through: was a valid Vendor ID provided in the payment request? Were all the required POST parameters provided in the payment request? Were all the provided parameters in the correct format? Was the transaction reference provided unique? This last one checks that the combination of Vendor ID and Transaction Reference are unique - you won’t be able to put through the same transaction twice, even using Vendor ID=1. Try it - you’ll get an error.Should your app require a Vendor ID of its own it is important that you include the Banking Information section on your App Details page. You are then required to log a ticket at our Developer Support Center under Technical Questions for a Vendor ID, pleasure supply your app name. Once this ID has been generated for it, the corresponding field will be updated in the Banking Information of your app for you.
Now that we have added billing the only API left to cover is the User
API, we are ready to proceed with something a bit more
challenging:retrieving the users contact list. Stay tuned for the sixth tutorial in the series!