background

Documentation



Merchant API Detail

## Your Merchant Params
Merchant Name:      Test MerchantMerchant ID:        999
Product Key:        b2662a1858df3d0c5ae502195f840be7be39079b

The MonaPay API allows developers to integrate our wallet system into their applications of any platform which is capable of displaying webpage for user interactivity. This wallet can easily be funded via User airtime balance or with any credit or debit cards. International cards can also be used.

Our cross-Platform payments solution can be called from any mobile or web application on any platform, that is capable launching a browser window ( or in-app browser) - without the user even leaving the app. When detecting that user is on a mobile device, AirPay’s payment pages automatically morph themselves into slick, small-screen-optimized version of our payment flow.

Payment flow can be opened in a pop up in app browser, inside an iframe or new browser window. When calling a payment flow, different payment initialization parameters should be specified in order to make the payment experience for your users as seamless as possible.


1. Payment Initialization

The process is to construct a payment url with the product detail and other params, the essential params are ref_id, merchant_id, key, uuid, amount and description of the transaction. The developer will have to load the generated url in the browser, or redirect the page to the url (in case of webapp) for user to interact with.

The generated pay url example:

https://www.monapay.com/v1/merchant/pay?reference_id=MG1545229048&merchant_id=999&key=b2662a1858df3d0c5ae502195f840be7be39079b&uuid=456789876543456796gvbndcvbnmnbv&amount=5000&description=Buy+MaliyoGame+Token5000+for+50+NGN

Parameters for payment url

  • [reference_id] - Max length: 50 This is a unique transaction id generated by the developer for his/her reference purpose note that this kotr2017-02-08 12:58:56 is not looking like a valid reference_id but to be on the safer side, rip all special characters off and use value that matches with this expression A-Za-z0-9 e.g: kotr20170208125856
  • [merchant_id] - Developer merchant account id
  • [product_key] - Product key, this is NOT the product secret key
  • [uuid] - This is user device id also known as guid, it will be advisable to rip off all special characters, in case of web app, a guid value can be generated and keep in broswer localstorage or cookie for later use, this will help in unique identification of a user or their browser.
  • [amount] - Amount in lowest unit, kobo for Nigerian currency
  • [description] - Max length: 100; Short description of the transaction
  • [redirect_url] - OPTIONAL; Redirect url after transaction is complete

Sample Code




1. Android

You can easily generate the payment url in your android code faster with the URI.Builder() class you can also read more on this link Use URI builder in Android or create URL with variables

Uri.Builder builder = new Uri.Builder();
builder.scheme("https")
    .authority("www.monapay.com")
    .appendPath("v1")
    .appendPath("merchant")
    .appendPath("pay")
    .appendQueryParameter("reference_id", "MG1545229048")
    .appendQueryParameter("merchant_id", "999")
    .appendQueryParameter("product_key", "b2662a1858df3d0c5ae502195f840be7be39079b")
    .appendQueryParameter("uuid", "web")
    .appendQueryParameter("amount", "5000")
    .appendQueryParameter("description", "Buy MaliyoGame Token5000 for 50 NGN");
    .appendQueryParameter("redirect_url", "https://www.monapay.com/v1/merchant/verifytransaction/MG1545229048");

String paymentUrl = builder.build().toString();

WebView webView = (WebView) findViewById(R.id.webView);
webView.loadUrl(paymentUrl);

    



2. iOS Objective-C

Introduced in iOS8 and OS X 10.10 is NSURLQueryItem, which can be used to build queries. You can also read more on this link Creating URL query parameters from NSDictionary objects in ObjectiveC

NSURLComponents *components = [NSURLComponents componentsWithString:@"http://www.monapay.com/v1/merchant/pay"];
NSURLQueryItem *reference_id = [NSURLQueryItem queryItemWithName:@"reference_id" value:@"MG1545229048"];
NSURLQueryItem *merchant_id = [NSURLQueryItem queryItemWithName:@"merchant_id" value:@"999"];
NSURLQueryItem *product_key = [NSURLQueryItem queryItemWithName:@"product_key" value:@"b2662a1858df3d0c5ae502195f840be7be39079b"];
NSURLQueryItem *uuid = [NSURLQueryItem queryItemWithName:@"uuid" value:@"456789876543456796gvbndcvbnmnbv"];
NSURLQueryItem *amount = [NSURLQueryItem queryItemWithName:@"amount" value:@"5000"];
NSURLQueryItem *description = [NSURLQueryItem queryItemWithName:@"description" value:@"Buy MaliyoGame Token5000 for 50 NGN"];
NSURLQueryItem *redirect_url = [NSURLQueryItem queryItemWithName:@"redirect_url" value:@"http://example.com/return.aspx?q=blah"];
components.queryItems = @[ reference_id, merchant_id, product_key, uuid, amount, description ];
NSURL *paymentUrl = components.URL;

[self.webView loadRequest:[NSURLRequest requestWithURL:paymentUrl]];



3. PHP for web

You can easily use our cross platform payment solution for your web application, here is a simple howto in PHP.

<?php
$referenceId = "MG1545229048";
$merchantId = "999";
$productKey = "b2662a1858df3d0c5ae502195f840be7be39079b";
$deviceUuid = "456789876543456796gvbndcvbnmnbv";
$amount = 5000;
$description = "Buy MaliyoGame Token5000 for 50 NGN";
$redirectUrl = "https://www.monapay.com/v1/merchant/verifytransaction/MG1545229048";

$data = array(
    "reference_id" => $referenceId,
    "merchant_id" => $merchantId,
    "product_key" => $productKey,
    "uuid" => $deviceUuid,
    "amount" => $amount,
    "description" => $description
    "redirect_url" => $redirectUrl
);

$paymentUrl = "https://www.monapay.com/v1/merchant/pay?" . http_build_query($data);

header("Location: $paymentUrl");

    


2. Payment Verification

Immediately after closing the popup browser(web) or in-app browser (native), the developer will make an HTTP GET request with the transaction reference id to fetch the status of the transaction.

Initialization endpoint:

https://www.monapay.com/v1/merchant/verifytransaction/PS1496421915

# https://www.monapay.com/v1/merchant/verifytransaction/PS1496421915
    
HTTP Request
GET /v1/merchant/verifytransaction/233000046342388898765 HTTPS/1.1
Host: www.monapay.com
Content-Type: application/json
Ocm-Spmi: Y5MC
Authentication: Basic b2662a1858df3d0c5ae502195f840be7be39079b
Cache-Control: no-cache
    
[Authentication] - Basic + the product key



Likely response [success]
{
    "status": "success",
    "data": {
        "id": "1009",
        "reference_id": "MG1545229048",
        "user_id": "89898",
        "temp_uuid": "456789876543456796gvbndcvbnmnbv",
        "type": "payment",
        "is_credit": "0",
        "product_key": "b2662a1858df3d0c5ae502195f840be7be39079b",
        "amount": "145000",
        "description": "transaction payment for E-Commerce transaction",
        "confirmed": "1",
        "confirmed_time": "2018-12-19 15:17:28",
        "successful": "1",
        "condition": "Successful",
        "created": "2016-12-19 16:07:44",
        "status": "1",
        "full_condition": "₦1450 being transaction payment for E-Commerce transaction : Successful. Balance: ₦0",
        "current_balance": 0
    }
}
    
Likely error
{
    "status": "error",
    "message": "Reference ID already exist",
    "code": "E0005"
}
    
  • [status] - status of error for all error reponse
  • [message] - reason for the error
  • [code] - internal error code

For further enquiries please send an email to support@monapay.com