Developers' Guide

.NET

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 mpower_dotnet_latest.tgz or mpower_dotnet_latest.zip to download our latest .NET assembly with dependencies.

using MPowerPayments;

API Configuration

Setting up your MPower API keys

MPowerSetup setup = new MPowerSetup {
  MasterKey = "dd6f2c90-f075-012f-5b69-00155d864600",
  PrivateKey = "test_private_oDLVlm1eNyh0IsetdhdJvcl0ygA",
  PublicKey = "test_public_zzF3ywvX9DE-OSDNhUqKoaTI4wc",
  Token = "ca03737cf942cf644f36",
  Mode = "test"
};

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.

MPowerStore store = new MPowerStore {
  Name = "Awesome Online Store",
  Tagline = "This is my awesome tagline",
  PhoneNumber = "030200001",
  PostalAddress = "P. O. Box 10770 Accra North Ghana",
  LogoUrl = "http://www.mylogourl.com/photo.png"
};

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
// Please note that the constructor requires a instance of both
// MPowerSetup & MPowerStore Classes respectively
MPowerCheckoutInvoice invoice = new MPowerCheckoutInvoice (setup, store);

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
// Please note that the constructor requires a instance of both
// MPowerSetup & MPowerStore Classes respectively
MPowerOnsiteInvoice invoice = new MPowerOnsiteInvoice (setup, store);

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 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.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 (100.50);

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 ()) {
  Console.WriteLine (invoice.Status);
  Console.WriteLine (invoice.ResponseText);
  Console.WriteLine (invoice.GetInvoiceUrl());
} else {
  Console.WriteLine (invoice.ResponseText);
  Console.WriteLine (invoice.Status);
}

(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
if (invoice.Create("MPOWER_CUSTOMER_USERNAME_OR_PHONENO")) {
  Console.WriteLine (invoice.Token);
  Console.WriteLine (invoice.Status);
  Console.WriteLine (invoice.ResponseText);
} else {
  Console.WriteLine (invoice.ResponseText);
  Console.WriteLine (invoice.Status);
}

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")) {
  Console.WriteLine(invoice.Status);
  Console.WriteLine(invoice.ResponseText);
  Console.WriteLine(invoice.GetReceiptUrl());
  Console.WriteLine(invoice.GetCustomerInfo("name"));
  Console.WriteLine(invoice.GetCustomerInfo("email"));
} else {
  Console.WriteLine(invoice.Status);
  Console.WriteLine(invoice.ResponseText);
}

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%)",30);
invoice.AddTax("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
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
MPowerStore store = new MPowerStore {
  CancelUrl = "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
MPowerStore store = new MPowerStore {
  ReturnUrl = "http://www.myawesomeshop.com/confirm.aspx"
};
 
// Setting the return URL on an invoice instance. 
// This will overwrite any global settings for return URL
invoice.SetReturnUrl("http://www.myawesomeshop.com/confirm.aspx");

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.

// Invoice token is returned as a URL query string "token"
// You are free to also explicitly check the status of an invoice
string InvoiceToken = "sjklsdll21-ms0w";
 
MPowerCheckoutInvoice invoice = new MPowerCheckoutInvoice (setup, store);
if (invoice.Confirm(InvoiceToken)) {
 
  // Retrieving Invoice Status
  // Status can be either completed, pending, canceled, fail
  Console.WriteLine (invoice.Status);
  Console.WriteLine (invoice.ResponseText);
 
  // You can retrieve the Name, Email & Phone Number 
  // of the customer using the callbacks below 
  Console.WriteLine (invoice.GetCustomerInfo("name"));
  Console.WriteLine (invoice.GetCustomerInfo("email"));
  Console.WriteLine (invoice.GetCustomerInfo("phone"));
  
  // Return the URL to the Invoice Receipt PDF file for download
  Console.WriteLine (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
  Console.WriteLine (invoice.GetCustomData("Firstname"));
  Console.WriteLine (invoice.GetCustomData("CartId"));
  Console.WriteLine (invoice.GetCustomData("Plan"));
 
  // You can also callback the total amount set earlier
  Console.WriteLine (invoice.GetTotalAmount());
 
}else{
  Console.WriteLine (invoice.GetStatus());
  Console.WriteLine (invoice.ResponseText);
  Console.WriteLine (invoice.ResponseCode);
}

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. Please note that MPowerDirectPay Class expects one parameter which should be an instance of the MPowerSetup Class

MPowerDirectPay direct_pay = new MPowerDirectPay (setup);
if(direct_pay.CreditAccount("MPOWER_CUSTOMER_USERNAME_OR_PHONENO",50)){
  Console.WriteLine(direct_pay.Description);
  Console.WriteLine(direct_pay.Status);
  Console.WriteLine(direct_pay.ResponseText);
}else{
  Console.WriteLine(direct_pay.ResponseText);
  Console.WriteLine(direct_pay.Status);
}