Developers' Guide

HTTP

Generating your API keys

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

Knowing MPower HTTP API

Our HTTP API is solely a JSON based API. All HTTP POST/GET/Response to/from the API service relies soles on JSON objects.

All JSON Objects returned in a response contains at least a response_code & response_text node name. The response_code node represents the technical code of the response, and the response_text node provides explanation of the response. Your application must rely heavily on these nodes in order to operate appropriately.

NOTE: All successful responses return a JSON Object node/name "response_code" with a value of "00".

Redirect Checkout Invoice

MPower redirect checkout invoice allows you to setup an invoice and redirect your customer back to our website to complete the checkout process. Our Redirect Checkout API is best suited for 99% of all web operations, the main advantege of this option is that customers can choose from an payment option available on our website as an when they are added and you need not change your code.

API Endpoints

#Sandbox Endpoint
https://app.mpowerpayments.com/sandbox-api/v1/checkout-invoice/create
 
#Live Endpoint
https://app.mpowerpayments.com/api/v1/checkout-invoice/create

HTTP POST Request Action

curl -H "Content-Type: application/json" \
-H "MP-Master-Key: dd6f2c90-f075-012f-5b69-00155d866600" \
-H "MP-Private-Key: test_private_amOI11Gb0SIo6NSLZr1xkfOYSuE" \
-H "MP-Token: d25e1f4ddc053779d526" \
-X POST -d '{"invoice": {"total_amount": 84, "description": "Optional Invoice Description Goes Here"},"store": {"name": "MPower Integration Store"}}' \
"https://app.mpowerpayments.com/sandbox-api/v1/checkout-invoice/create"

Expected Response

{
    "response_code":"00",
    "response_text":"https://app.mpowerpayments.com/sandbox-checkout/invoice/test_a29da726a1",
    "description":"Checkout Invoice Created",
    "token":"test_a29da726a1"
}

Onsite Payment Request (OPR)

OPR allows you to charge MPower Customers directly inside your application or website. OPR is a two step process. Remember setup an MPower Sandbox Customer Account when testing the OPR API.

NOTE: Onsite Payment Request (OPR) is only used on customers who have opened an MPower Account.

Step 1 (OPR Token Request)

This step requires you to take MPower Customer username/mobile to complete the first process.

API Endpoints
#Sandbox Endpoint
https://app.mpowerpayments.com/sandbox-api/v1/opr/create
 
#Live Endpoint
https://app.mpowerpayments.com/api/v1/opr/create
HTTP POST Request Action
curl -H "Content-Type: application/json" \
-H "MP-Master-Key: dd6f2c90-f075-012f-5b69-00155d866600" \
-H "MP-Private-Key: test_private_amOI11Gb0SIo6NSLZr1xkfOYSuE" \
-H "MP-Token: d25e1f4ddc053779d526" \
-X POST -d '{"invoice_data" : {"invoice": {"total_amount": 84, "description": "Optional Invoice Description Goes Here"},"store": {"name": "MPower Integration Store"}},"opr_data" :{"account_alias" : "mpowertester"}}' \
"https://app.mpowerpayments.com/sandbox-api/v1/opr/create"
Expected Response

Successfull completion returns a JSON object. You application will have to save the token key for the final step of the OPR process. At this stage the MPower customer also receives a confirmation code via Email and SMS(Live transactions only).

{
    "response_code":"00",
    "response_text":"OPR-test_d6fdea",
    "description":"Onsite Payment Request successfully sent.",
    "token":"OPR-test_56a1c3",
    "invoice_token":"test_1655bf36cd"
}

Step 2 (OPR Charge)

This final step requires your OPR Token together with the Customer's confirmation code to complete.

API Endpoints
#Sandbox Endpoint
https://app.mpowerpayments.com/sandbox-api/v1/opr/charge
 
#Live Endpoint
https://app.mpowerpayments.com/api/v1/opr/charge
HTTP POST Request Action
curl -H "Content-Type: application/json" \
-H "MP-Master-Key: dd6f2c90-f075-012f-5b69-00155d866600" \
-H "MP-Private-Key: test_private_amOI11Gb0SIo6NSLZr1xkfOYSuE" \
-H "MP-Token: d25e1f4ddc053779d526" \
-X POST -d '{ "token" : "OPR-test_56a1c3", "confirm_token" : "4346" }' \
"https://app.mpowerpayments.com/sandbox-api/v1/opr/charge"
Expected Response

Successfull completion returns a JSON object with contains the customer details and the URL to the PDF receipt.

{
    "response_code":"00",
    "response_text":"Payment received",
    "description":"Customer has been charged successfully",
    "invoice_data": {
        "invoice": {
            "total_amount":84,
            "description":"Optional Invoice Description Goes Here"
        },
        "mode":"test",
        "status":"completed",
        "customer": {
            "name":"Jonny Test Account",
            "phone":"0243125678",
            "email":"test@mpowerpayments.com"
        },
        "receipt_url":"https://app.mpowerpayments.com/sandbox-checkout/receipt/pdf/test_74f4ff3ad4.pdf"
    }
}

DirectPay API

You can programmatically transfer funds from your MPower Account to other MPower customers via DirectPay API. For security purposes, you must expicitly enable direct pay option in your integration setup. If can always enable or disable direct pay option by updating your integration setup.

API Endpoints

#Sandbox Endpoint
https://app.mpowerpayments.com/sandbox-api/v1/direct-pay/credit-account
 
#Live Endpoint
https://app.mpowerpayments.com/api/v1/direct-pay/credit-account

HTTP POST Request Action

curl -H "Content-Type: application/json" \
-H "MP-Master-Key: dd6f2c90-f075-012f-5b69-00155d866600" \
-H "MP-Private-Key: test_private_amOI11Gb0SIo6NSLZr1xkfOYSuE" \
-H "MP-Token: d25e1f4ddc053779d526" \
-X POST -d '{ "account_alias" : "0244124660", "amount" : 30.50 }' \
"https://app.mpowerpayments.com/sandbox-api/v1/direct-pay/credit-account"

Expected Response

{
    "response_code":"00",
    "response_text":"Transaction completed successfully",
    "description":"Success! Amount of GHS 30.5 has been transfered to Sandbox Account JOHN TEST ACCOUNT",
    "transaction_id":"TEST000001"
}

DirectMobile API Charge

You can charge mobile money wallets directly from your application or website. This is good for apps that do not want to redirect to our checkout page or mobile apps that need to charge customers.

NOTE: DirectMobile API currently supports only MTN Mobile Money & Airtel Money and should only be used with your Live API keys.

API Endpoints

#Charging
https://app.mpowerpayments.com/api/v1/direct-mobile/charge
 
#Status Check
https://app.mpowerpayments.com/api/v1/direct-mobile/status

Mobile Charge Request

curl -H "Content-Type: application/json" \
-H "MP-Master-Key: dd6f2c90-f075-012f-5b69-00155d866600" \
-H "MP-Private-Key: live_private_amOI11Gb0SIo6NSLZr1xkfOYSuE" \
-H "MP-Token: d25e1f4ddc053779d526" \
-X POST -d '{ "customer_name" : "Alfred Robert Rowe", "customer_phone" : "0244124661", "customer_email" : "customer@domainname.com", "wallet_provider" : "MTN", "merchant_name" : "Classic Shoes Ltd", "amount" : "10" }' \
"https://app.mpowerpayments.com/api/v1/direct-mobile/charge"

Charge Response

{
    "response_code":"00",
    "response_text":"Mobile wallet payment request has been issued.",
    "description":"You will receive a bill prompt shortly on your number 0244124661 with invoice no. 200108765, kindly complete it.",
    "transaction_id":"DTX012248",
    "token":"6d875bf6f28b4c5d01e58e7c",
    "mobile_invoice_no":"200108765"
}

Checking Payment Status

Because of the nature of mobile money, you will have to keep your transaction token and use it to check if payment has been completed by the customer. When an invoice is found the status would either be pending,cancelled or completed depending on whether or not the customer has made payment for the transaction.

curl -H "Content-Type: application/json" \
-H "MP-Master-Key: dd6f2c90-f075-012f-5b69-00155d866600" \
-H "MP-Private-Key: live_private_amOI11Gb0SIo6NSLZr1xkfOYSuE" \
-H "MP-Token: d25e1f4ddc053779d526" \
-X POST -d '{ "token" : "6d875bf6f28b4c5d01e58e7c"}' \
"https://app.mpowerpayments.com/api/v1/direct-mobile/status"

Status Response

Always remember to use the JSON key tx_status to check the real status of the transaction

Failure response:

{
    "response_code":"00",
    "response_text":"Transaction Found",
    "description":"CANCELLED Transaction",
    "tx_status":"cancelled",
    "transaction_id":"DTX012248",
    "mobile_invoice_no":"200108765",
    "cancel_reason":"Insufficient Funds. Unable to send bill prompt to complete payment."
}

Success response:

{
    "response_code":"00",
    "response_text":"Transaction Found",
    "description":"COMPLETE Transaction",
    "tx_status":"complete",
    "transaction_id":"DTX012253",
    "mobile_invoice_no":"200108770",
    "cancel_reason":null
}

Checking Invoice Status

When you POST a Checkout Redirect Invoice or Onsite Payment Request Invoice, MPower returns an invoice token JSON node. You can use the value of this token to programmatically check the status of an invoice even if the customer is on our checkout page completing the payment process.

When an invoice is found the status would either be pending,cancelled or completed depending on whether or not the customer has made payment for the transaction.

NOTE: Always remember to append the API Endpoints with the value of your invoice token.

API Endpoints

#Sandbox Endpoint
https://app.mpowerpayments.com/sandbox-api/v1/checkout-invoice/confirm/[invoice_token]
 
#Live Endpoint
https://app.mpowerpayments.com/api/v1/checkout-invoice/confirm/[invoice_token]

HTTP GET Request Action

curl -H "Content-Type: application/json" \
-H "MP-Master-Key: dd6f2c90-f075-012f-5b69-00155d866600" \
-H "MP-Private-Key: test_private_amOI11Gb0SIo6NSLZr1xkfOYSuE" \
-H "MP-Token: d25e1f4ddc053779d526" \
https://app.mpowerpayments.com/sandbox-api/v1/checkout-invoice/confirm/test_1655bf36cd

Expected Response

{
    "response_code":"00",
    "response_text":"Transaction Found",
    "invoice": {
        "items":{},
        "taxes":{},
        "total_amount":325,
        "description":"a tin of milk"
    },
    "custom_data":{},
    "actions": {
        "cancel_url":"",
        "return_url":""
    },
    "status":"completed"
}

Full JSON Structure

Below is the full structure of the MPower Invoice JSON Object. Not all nodes are required, but the extra nodes provide you with more flexibilty and customization you may need when the need arises.

The root node invoice with its child node total_amount & description are mandatory. The root node store with its child node name are also mandatory. These are the only mandatory JSON nodes needed when making an invoice HTTP POST to our API Endpoint.

{
  "invoice": {
    "items": {
      
    },
    "taxes": {
      
    },
    "total_amount": 200,
    "description": "Description of the invoice here"
  },
  "store": {
    "name": "Store Name",
    "tagline": "Tagline of the online store",
    "postal_address": "Box 10770 Accra - Ghana",
    "phone": "233244124660",
    "logo_url": "",
    "website_url": ""
  },
  "custom_data": {
    
  },
  "actions": {
    "cancel_url": "",
    "return_url": ""
  }
}

Adding Invoice Items

Refer to the full JSON structure to know exactly where the following structure will be fitted. Invoice items are used basically for representational purposes on the checkout page. MPower will not use any of the amounts declared to charge the customer.

"items": {
    "item_0": {
      "name": "VIP Ticket",
      "quantity": 2,
      "unit_price": "35.0",
      "total_price": "70.0",
      "description": "VIP Tickets for the MPower Event"
    },
    "item_1": {
      "name": "Regular Ticket",
      "quantity": 1,
      "unit_price": "25.0",
      "total_price": "0.0",
      "description": ""
    }
}

Adding Tax Information

You can represent tax information on your invoice by using the following JSON node.

"taxes": {
  "tax_0": {
    "name": "VAT",
    "amount": 50
  },
  "tax_1": {
    "name": "NHIS Tax",
    "amount": 20
  }
}

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": {
  "phone_brand": "Nexus 4",
  "IMEI": "72827282891010",
  "model": "Mako"
}

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.

"actions": {
  "cancel_url": "http://www.yourwebsite.com/cancelurl"
}

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.

"actions": {
  "return_url": "http://www.yourwebsite.com/return"
}