Mobiamo

Mobiamo is a mobile SMS payment method which connects you to over 240 mobile network operators. You can build your own mobile payment experience into your application by integrating it.

Integration

Integrating Mobiamo Direct only requires 4 steps:

Get API token

Please check the code sample below for how to generate the token. You can also refer to get API token for more information.

<?php
require_once('path-to-paymentwall-lib/paymentwall.php');

Paymentwall_Config::getInstance()->set(array(
	'public_key' => 'YOUR_PROJECT_KEY', 
	'private_key' => 'YOUR_SECRET_KEY'
));

$model = new Paymentwall_Mobiamo();
$response = $model->getToken(['uid' => 'user40012']); 

$token = $response['token'];
?>

If the request is performed successfully, the token will be included in the response. You will use the token for the next two steps. Here is the sample response

{
	"success": true,
	"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDM2NDQ3NzIsImp0aSI6Ik5IcWN0QjZEbGR3bjNmQWxSZ1VuXC8zWkRhQjI1R1dvZlpSelJcL0JMYzNhTT0iLCJleHAiOjE1MDM3MzExNzIsImRhdGEiOnsibWVyY2hhbnRJZCI6IjIiLCJ0aW1lc3RhbXAiOiIxNTAzNjQ0NzEzIiwicHJvamVjdF9pZCI6IjE4MjgxNSJ9fQ.R5jLTYV23qRDaMbHZlun6MDFbWfK9xXTMzPIzNglr0A",
	"expire_time": 86400
}

Initiate payment

After you get the token, you can use it to initiate the payment along with the information about your product. The purpose of this step is to get the flow that the user will have to go through to make payment. The instructions for each flow is also included in the response. There are three main flows:

  • msisdn: you have to collect the phone number from user and this number will be sent in Process payment step to process the transaction.

In certain countries, after you send the request to process the payment with the phone number, you will receive code flow in the response and you will have to send another request to fulfill the code flow

  • code: users receive the code after sending the message with the keyword to shortcode in the instructions and the code is sent in Process payment step.

  • redirect: if this flow is returned, there is no need to send process payment request. Please redirect the user to the URL which is included in the response.

Please note that carrier (ID of the mobile carrier) is expected to be sent in the request for some countries. The list of ID is provided in Mobiamo Carriers.

This line of code is to initiate the payment:

<?php
$initiate = $mobiamo->initPayment(
	$token, 
	[
		'uid' => 'user40012', 
		'amount' => 2000, 
		'currency' => 'PHP', 
		'country' => 'PH', 
		'product_id' => 123, 
		'product_name' => 'product101', 
		'carrier' => 255
	]
);
?>

Along with the flow and instructions, ref is also sent in the response for you to prepare for Process payment step.

{
	"ref": "w123456789",
	"flow": "msisdn",
	"instructions": {},
	"price": {
		"amount": 2000,
		"currency": "PHP",
		"formatted": "PHP 2,000.00",
		"carriers": [{
			"id": 255,
			"name": "Globe"
		}]
	},
	"product_name": "coins",
	"success": true
}

Process payment

This request is to process the transaction with the information you collect from the users. What you need to pass in the parameter data depends on the flow you receive in Initiate payment step.

Here is the code sample to send the request:

<?php
$process = $mobiamo->processPayment(
	$token, 
	[
		'uid' => 'user40012', 
		'ref' => $ref, 
		'flow' => $flow, 
		'data' => 'USER_DATA'
	]
);
?>

If the payment is successful you will receive response like the following:

{
	"success": true
}
  • For the case that is mentioned in Initiate payment step, code flow will be returned and you will have to send another request to process the payment with the code collected from users.
{
	"success": true,
	"instructions": {
		"shortcode": "2800",
		"keyword": "PW2000",
		"info": "VAT included. For customer support, please contact us at support@mobiamo.com"
	},
	"flow": "code"
}

Handle pingback

On your server side, put the following code as an online server interface to interact with our Pingback:

<?php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'api_type' => Paymentwall_Config::API_GOODS,
    'public_key' => 'YOUR_APPLICATION_KEY', // available in your Paymentwall merchant area
    'private_key' => 'YOUR_SECRET_KEY', // available in your Paymentwall merchant area
));

$pingback = new Paymentwall_Pingback($_GET, $_SERVER['REMOTE_ADDR']);
if ($pingback->validate(true)) {
    $productId = $pingback->getProduct()->getId();
    if ($pingback->isDeliverable()) {
        // deliver the product
    } else if ($pingback->isCancelable()) {
        // withdraw the product
    } else if ($pingback->isUnderReview()) {
        // set "pending" as order status
    }
    echo 'OK'; // Paymentwall expects response to be OK, otherwise the pingback will be resent
} else {
    echo $pingback->getErrorSummary();
}
?>

var Paymentwall = require('paymentwall');
Paymentwall.Configure(
    Paymentwall.Base.API_GOODS,
    'YOUR_PROJECT_KEY',
    'YOUR_SECRET_KEY'
);

var pingback = new Paymentwall.Pingback("query data in pingback request", "ip address of pingback");
if (pingback.validate(true)) {
    var productId = pingback.getProduct().getId();
    if (pingback.isDeliverable()) {
        // deliver the product
    } else if (pingback.isCancelable()) {
        // withdraw the product
    } 
    console.log('OK'); // Paymentwall expects the string OK in response, otherwise the pingback will be resent
} else {
    console.log(pingback.getErrorSummary());
}

import com.paymentwall.java.*;

Config.getInstance().setLocalApiType(Config.API_GOODS);
Config.getInstance().setPublicKey("YOUR_PROJECT_KEY");
Config.getInstance().setPrivateKey("YOUR_SECRET_KEY");

Pingback pingback = new Pingback(request.getParameterMap(), request.getRemoteAddr());
if (pingback.validate(true)) {
    String goods = pingback.getProductId();
    String userId = pingback.getUserId();
    if (pingback.isDeliverable()) {
        // deliver Product to user with userId
    } else if (pingback.isCancelable()) {
        // withdraw Product from user with userId
    }
    return "OK";
} else {
    return pingback.getErrorSummary();
}

require 'paymentwall' # alternatively, require_relative '/path/to/paymentwall-ruby/lib/paymentwall.rb'
Paymentwall::Base::setApiType(Paymentwall::Base::API_GOODS)
Paymentwall::Base::setAppKey('YOUR_PROJECT_KEY') # available in your Paymentwall merchant area
Paymentwall::Base::setSecretKey('YOUR_SECRET_KEY') # available in your Paymentwall merchant area

pingback = Paymentwall::Pingback.new(request_get_params, request_ip_address)
if pingback.validate(true)
    productId = pingback.getProduct().getId()
    if pingback.isDeliverable()
        # deliver the product
    elsif pingback.isCancelable()
        # withdraw the product
    end 
    puts 'OK' # Paymentwall expects response to be OK, otherwise the pingback will be resent
else
    puts pingback.getErrorSummary()
end

from paymentwall import *
Paymentwall.set_api_type(Paymentwall.API_GOODS)
Paymentwall.set_app_key('YOUR_PROJECT_KEY') # available in your merchant area
Paymentwall.set_secret_key('YOUR_SECRET_KEY') # available in your merchant area

pingback = Pingback({x:y for x, y in request.args.iteritems()}, request.remote_addr)

if pingback.validate(True):
    product_id = pingback.get_product().get_id()
    if pingback.is_deliverable():
        # deliver the product
        pass
    elif pingback.is_cancelable():
        # withdraw the product
        pass

    print('OK') # Paymentwall expects response to be OK, otherwise the pingback will be resent

else:
    print(pingback.get_error_summary())

using Paymentwall;

Paymentwall_Base.setApiType(Paymentwall_Base.API_GOODS);
Paymentwall_Base.setAppKey("YOUR_PROJECT_KEY"); // available in your Paymentwall merchant area
Paymentwall_Base.setSecretKey("YOUR_SECRET_KEY"); // available in your Paymentwall merchant area


NameValueCollection parameters = Request.QueryString;
Paymentwall_Pingback pingback = new Paymentwall_Pingback(parameters, HttpContext.Current.Request.ServerVariables["REMOTE_ADDR"]);
if (pingback.validate(true))
{
    string productId = pingback.getProduct().getId();
    if (pingback.isDeliverable())
    {
        //deliver the product
    }
    else if (pingback.isCancelable())
    {
        //withdraw the product
    }
    Response.Write("OK"); // Paymentwall expects response to be OK, otherwise the pingback will be resent
}
else {
    Response.Write(pingback.getErrorSummary());
}

A pingback request typically contains all the information for you to do the product delivery. As an addition, Paymentwall provides a series of reversed parameters as custom pingback parameters for specific needs, you can also add your own parameters as custom pingback parameter in order to implement parameter transmission.

Below is a sample with default format:

http://www.yourserver.com/pingback_path?uid=pwuser&goodsid=gold_membership&slength=&speriod=&type=0&ref=b1493096790&sign_version=2&sig=d94b23ba8585f29978706dd1b153ead9

After validating the pingback, your server is always expected to be able to proceed the delivery process and respond to it with only OK in the body of response.

Configuration

Configure your project in merchant dashboard to make it work properly with Mobiamo Direct API.

  • Select Your API as Checkout API in Settings.

  • Fill the Pingback URL to receive asynchronous notification in Settings.

  • Email to devsupport@paymentwall.com with your project key to enable Mobiamo Direct API for your project.

Please make sure you have enabled Mobiamo in Payment System section.

Questions?

Common questions are covered in the FAQ.
For integration and API questions, feel free to reach out Integration Team via integration@paymentwall.com.
For business support, email us at merchantsupport@paymentwall.com.
To contact sales, email bizdev@paymentwall.com.

To suggest a change to this documentation you can submit a pull request on GitHub.