Developers' Guide


Generating your API keys

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

Library Installation & Setup

Installing MPower using gem command

gem install mpower

Installing MPower using bundler. Add the following to your Gemfile

gem "mpower"

API Configuration

If your are using Rails, you may create an initialiser script in your the config/initializers/ directory and place your settings there.

MPower::Setup.master_key = "sdd6f2c90-f075-01d2f-5b69-00155d866600"
MPower::Setup.public_key = "test_public_zzF34wvX9DE-OSDNhUqKoaTI4wc"
MPower::Setup.private_key = "test_private_oDLVfm1e3yh0IsetdhdJvcl0ygA"
MPower::Setup.mode = "test"
MPower::Setup.token = "ca03737cf942cfg44f36"

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.

Note: You may add this code to your initializer scripts if your are on Rails = "My Awesome Online Store"
MPower::Checkout::Store.tagline = "My awesome store's awesome tagline"
MPower::Checkout::Store.postal_address = "Post office Box AN 10604"
MPower::Checkout::Store.phone_number = "0302507099"

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 =

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/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 =

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.add_item("13' Apple Retina 500 HDD",1,10.99,10.99);
invoice.add_item("Case Logic laptop Bag",2,100.50,201,"Optional description");
invoice.add_item("Philips electric shaver",2,50.50,101.00);
# You can optionally set a generation 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.description = "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.

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
  puts invoice.status
  puts invoice.response_text
  # you may want to do "redirect_to invoice.invoice_url" in a Rails controller
  puts invoice.invoice_url
  puts invoice.status
  puts 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 as the parameter
  puts invoice.status
  puts invoice.response_text
  puts invoice.token
  puts invoice.status
  puts 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
  puts invoice.status
  puts invoice.response_text
  puts invoice.receipt_url
  puts invoice.get_customer_info("name")
  puts invoice.get_customer_info("email")
  puts invoice.status
  puts 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.add_tax("VAT (15%)",30);
invoice.add_tax("NHIL (5%)",10);

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

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.cancel_url = ""
# Setting the cancel URL on an invoice instance. 
# This will overwrite any global settings for cancel URL
invoice.cancel_url = ""

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.return_url = ""
# Setting the return URL on an invoice instance. 
# This will overwrite any global settings for return URL
invoice.return_url = ""

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.

# Get the token prameter from the QUERYSTRING if you are on Rails or Sinatra
token = params[:token]
invoice =
if invoice.confirm(token)
  # Retrieving Invoice Status
  # Status can be either completed, pending, canceled, fail
  puts invoice.status
  # You can retrieve the Name, Email & Phone Number 
  # of the customer using the callbacks below 
  puts invoice.get_customer_info "name"
  puts invoice.get_customer_info "email"
  puts invoice.get_customer_info "phone"
  # Return the URL to the Invoice Receipt PDF file for download
  puts invoice.receipt_url
  # Retrieving any custom data you have added to the invoice
  # Please remember to use the right keys you used to set them earlier
  puts invoice.get_custom_data "Firstname"
  puts invoice.get_custom_data "CartId"
  puts invoice.get_custom_data "Plan"
  # You can also callback the total amount set earlier
  puts invoice.total_amount
  puts invoice.status
  puts invoice.response_text
  puts invoice.response_code

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 =
if (direct_pay.credit_account("CUSTOMER_MPOWER_USERNAME_OR_PHONE", 100))
  puts direct_pay.description
  puts direct_pay.response_text
  puts direct_pay.transaction_id
  puts direct_pay.description
  puts direct_pay.response_text