background

Documentation

Merchant API Detail

## Your Merchant Params
Merchant Name:      Test Merchant 
Merchant ID:        123

The AirPay 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:
# http://beta.monapay.com:80/v1/merchant/pay?reference_id=MG1489414003&merchant_id=3&product_key=25ab5370735e2039
1ce2df6329df5c1d9fa15c41&uuid=456789876543456796gvbndcvbnmnbv&amount=1000&description=Buy+MaliyoToken5000+for+10+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
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("http")
    .authority("beta.monapay.com:80")
    .appendPath("v1")
    .appendPath("merchant")
    .appendPath("pay")
    .appendQueryParameter("reference_id", "MG1489414003")
    .appendQueryParameter("merchant_id", "3")
    .appendQueryParameter("product_key", "25ab5370735e20391ce2df6329df5c1d9fa15c41")
    .appendQueryParameter("uuid", "456789876543456796gvbndcvbnmnbv")
    .appendQueryParameter("amount", "20000")
    .appendQueryParameter("description", "Buy MaliyoToken5000 for 200 NGN");
    
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://beta.monapay.com:80/v1/merchant/pay"];
NSURLQueryItem *reference_id = [NSURLQueryItem queryItemWithName:@"reference_id" value:@"MG1489414003"];
NSURLQueryItem *merchant_id = [NSURLQueryItem queryItemWithName:@"merchant_id" value:@"3"];
NSURLQueryItem *product_key = [NSURLQueryItem queryItemWithName:@"product_key" value:@"25ab5370735e20391ce2df6329df5c1d9fa15c41"];
NSURLQueryItem *uuid = [NSURLQueryItem queryItemWithName:@"uuid" value:@"456789876543456796gvbndcvbnmnbv"];
NSURLQueryItem *amount = [NSURLQueryItem queryItemWithName:@"amount" value:@"20000"];
NSURLQueryItem *description = [NSURLQueryItem queryItemWithName:@"description" value:@"Buy MaliyoToken5000 for 200 NGN"];
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 = "MG" . time();
$merchantId = "3";
$productKey = "25ab5370735e20391ce2df6329df5c1d9fa15c41";
$deviceUuid = "456789876543456796gvbndcvbnmnbv";
$amount = 20000;
$description = "Buy MaliyoToken5000 for 200 NGN";

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

$paymentUrl = "http://beta.monapay.com:80/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:
# http://beta.monapay.com:80/v1/merchant/verifytransaction/233000046342388898765
HTTP Request
GET /v1/merchant/verifytransaction/233000046342388898765 HTTP/1.1
Host: beta.monapay.com:80
Content-Type: application/json
Ocm-Spmi: Y5MC
Authentication: Basic a61c4c0873d3a94a8fe5ccb2fbbd319b91e98798
Cache-Control: no-cache
[Authentication] - Basic + the product key



Likely response [success]
{
    "status": "success",
    "data": {
        "id": "1009",
        "reference_id": "233000046342388898765",
        "user_id": "299",
        "temp_uuid": "456789876543456796gvbndcvbnmnbv",
        "type": "payment",
        "is_credit": "0",
        "product_key": "a61c4c0873d3a94a8fe5ccb2fbbd319b91e98798",
        "amount": "145000",
        "description": "transaction payment for E-Commerce transaction",
        "confirmed": "1",
        "confirmed_time": "2017-05-17 12:22:04",
        "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 contact the admin.