Developers' Guide

PHP

Generating your API keys

Click Here to follow our guide on how to set up and generate your MPower integration APIs

Library Installation & Setup

Click Here to download our latest php client library.

API Configuration

Remember to include the mpower library in your PHP file. You can create a global configuration file with these settings and include them in your subscequent files.

MPower_Setup::setMasterKey("dd6f2c90-f075-012f-5b69-00155d866600");
MPower_Setup::setPublicKey("test_public_oDLVlm1eNyh0IsetdhdJvcl0ygA");
MPower_Setup::setPrivateKey("test_private_zzF3ywvX9DE-OSDNhUqKoaTI4wc");
MPower_Setup::setMode("test");
MPower_Setup::setToken("ca03737cf942cf644f36");

Checkout Store Configuration

You may set up your online store information as depicted below. MPower uses these settings in setting up your store information on the checkout page, invoice & receipt printouts and PDF downloads.

//Setup your Store information
MPower_Checkout_Store::setName("My Awesome Online Store");
MPower_Checkout_Store::setTagline("My awesome store's awesome tagline");
MPower_Checkout_Store::setPhoneNumber("0302507099");
MPower_Checkout_Store::setPostalAddress("Post office Box AN 10604");

Initialize a Checkout Invoice

MPower checkout invoice is a simplest implementation possible. It requires you to redirect to your customer to our checkout page to accept payments and complete the transaction

// If you intend to use a simpler approach by redirecting to the MPower checkout page
$invoice = new MPower_Checkout_Invoice();

Initialize an Onsite Invoice

Depending on your needs your may want to charge your MPower customers directly on your website or inside your mobile application or POS Device. MPower Onsite Invoice uses our OPR (Onsite Payment Request) API to securely allow you to charge customers without disclosing customers sensitive data on your service.

MPower OPR is a two step process which requires the following.

  1. Take the username or phone number of an the MPower customer and create the Invoice. MPower will return an OPR Token and SMS(Live transactions only)/Email the customer with Confirmation Code
  2. Accept the customer's Confirmation Code and add it to the OPR Token received to make the actual charge.
// If you wish to accept payments directly on your service
$invoice = new MPower_Onsite_Invoice();

Add Invoice Items & Description

MPower eliminates the traditional form post checkout technique and uses simple API methods to help you easily build and prepare your checkout information for submission

Please note that MPower does not perform any calculations on the checkout items submitted. The information provided is strictly for representational purposes and you will need to call our 'setTotalAmount' API method to instruct us on the exact amount to charge.

/* Adding items to your invoice is very basic, the parameters expected are 
name_of_item, quantity, unit_price, total_price and optional item
description. */
$invoice->addItem("13' Apple Retina 500 HDD",1,10.99,10.99);
$invoice->addItem("Case Logic laptop Bag",2,100.50,201,"Optional description");
$invoice->addItem("Philips electric shaver",2,50.50,101.00);

/* You can optionally set a general invoice description text which can 
be used in cases where your invoice does not need an items list or in cases
where you need to include some extra descriptive information to your invoice */
$invoice->setDescription("Optional Invoice description here");

Setting Total Amount Chargable

MPower expects a total charge amount set. This is the actual amount that is charged to your customer. It is considered that you would have made all calculations at on your server before setting this amount.

NOTE: MPower will not perform any calculations on our servers. The charge amount set from your sever will be what MPower will charge your customer.

$invoice->setTotalAmount(1200.99);

Redirecting to MPower Checkout

After adding items to your invoice and setting your total amount, redirecting your customer is just a method call away. Please note that the "$invoice->create()" method returns true or false depending if the invoice was successfully created or not. This allows you to put it in an if else statement for better management.

// The code below depicts how to create the checkout invoice on our servers
// and redirect to the checkout page.
if($invoice->create()) {
   header("Location: ".$invoice->getInvoiceUrl());
}else{
  echo $invoice->response_text;
}

(OPR) Onsite Payment Request

After adding items to your invoice and setting your total amount, accept the MPower customer's username or phone number and start an OPR request. Remember to keep

// Onsite Payment Request requires the mpower customer account alias or phone number as the parameter
if ($invoice->create("MPOWER_CUSTOMER_USERNAME_OR_PHONENO")) {
  echo $invoice->getStatus();
  echo $invoice->token;
  echo $invoice->getReceiptUrl();
} else {
  echo $invoice->getStatus();
  echo $invoice->response_text;
}

Issuring an OPR Charge

To successfully complete an OPR charge, you need both your OPR Token & the Confirmation code sent to the customer. After a successfull charge you can programatically access the receipt url, customer information and more.

// Onsite Payment Request Charge requires bother the OPR_Token & Customers Confirmation Token
if($invoice->charge("OPR_TOKEN","CUSTOMER_CONFIRM_TOKEN")) {
  echo $invoice->getStatus();
  echo $invoice->response_text;
  echo $invoice->getReceiptUrl();
  echo $invoice->getCustomerInfo("name");
  echo $invoice->getCustomerInfo("email");
} else {
  echo $invoice->getStatus();
  echo $invoice->response_text;
}

Extra API Methods

Adding Tax Information

You may include tax information on on the checkout page. This information will be available on the invoice & receipt printouts and PDF downloads.

// The parameters for setting add tax are title_of_the_tax, tax_amount
$invoice->addTax('VAT (15%)',50);
$invoice->addTax('NHIL (5%)',50);

Adding Custom Data

There are times when you may need to add an extra load of data with the checkout information for later use. MPower allows saving of custom data on our servers which are persisted even after successful payment.

NOTE: Custom data is not displayed anywhere on the checkout page, invoice/receipt download & printouts. Its purely called up programmatically using our confirm API callback action

// Custom data allows you to add extra data to the invoice information 
// which can be accessed via our confirm API callback
$invoice->addCustomData("Firstname","Alswell");
$invoice->addCustomData("Lastname","Cobbinah");
$invoice->addCustomData("CartId",450021);
$invoice->addCustomData("Plan","JUMBO");

Setting a Cancel URL

You can optionally set the URL where your customers will be redirected to after canceling a checkout.

NOTE: There are two options as to how the cancel URL is set, one is to set it globally using the checkout setup information and the other is set it as per checkout invoice.

Setting the cancel URL directly on the invoice instance will overwrite the global settings if already set.

// Globally setting cancel URL, the piece of code below 
// should be included with the checkout shop setup code
MPower_Checkout_Store::setCancelUrl("http://www.myawesomeshop.com/");

// Setting the cancel URL on an invoice instance. 
// This will overwrite any global settings for cancel URL
$invoice->setCancelUrl("http://www.myawesomeshop.com/");

Setting a Return URL

MPower does a good job of managing receipt downloads and printouts after your customer successfuly makes payment. However there may be cases where you may descide to redirect your customers to another URL after successfully making payment. Return URL guarantees this action.

NOTE: MPower will append ?token=INVOICE_TOKEN to your URL, how to use this token is shown in the next topic.

// Globally setting return URL, the piece of code below 
// should be included with the checkout shop setup code
MPower_Checkout_Store::setReturnUrl("http://www.myawesomeshop.com/confirm.php");

// Setting the return URL on an invoice instance. 
// This will overwrite any global settings for return URL
$invoice->setReturnUrl("http://www.myawesomeshop.com/confirm.php");

Confirming a Checkout Programatically

Our API allows you to check on the status of any checkout using the checkout token key. You have access to all the data including the receipt download link & customer information in cases where the checkout has been confirmed as completed.

// MPower will automatically set the confirm token to QUERY_STRING 
// param $_GET['token'] if not explicitly specified
$token = $_GET["token"];

$invoice = new MPower_Checkout_Invoice();
if ($invoice->confirm($token)) {

  // Retrieving Invoice Status
  // Status can be either completed, pending, canceled, fail
  print $invoice->getStatus();

  // You can retrieve the Name, Email & Phone Number 
  // of the customer using the callbacks below 
  print $invoice->getCustomerInfo('name');
  print $invoice->getCustomerInfo('email');
  print $invoice->getCustomerInfo('phone');
  
  // Return the URL to the Invoice Receipt PDF file for download
  print $invoice->getReceiptUrl();

  // Retrieving any custom data you have added to the invoice
  // Please remember to use the right keys you used to set them earlier
  print $invoice->getCustomData("Firstname");
  print $invoice->getCustomData("CartId");
  print $invoice->getCustomData("Plan");

  // You can also callback the total amount set earlier
  print $invoice->getTotalAmount();

}else{
  print $invoice->getStatus();
  print $invoice->response_text;
  print $invoice->response_code;
}

SendMoney via MPower DirectPay

You can pay any MPower account directly via your third party apps. This is particularly excellent for implementing your own Adaptive payment solutions on top of MPower.

$direct_pay = new MPower_DirectPay();
if ($direct_pay->creditAccount("MPOWER_CUSTOMER_USERNAME_OR_PHONENO",70.65)) {
  print $direct_pay->description;
  print $direct_pay->response_text;
  print $direct_pay->transaction_id;
}else{
  print $direct_pay->response_text;
}