Documentation

Accept in-app payments with Paymentwall’s advanced mobile payment solution. Mobiamo is a mobile carrier billing platform with global coverage. Our Android SDK was designed to enable 1-click payments via mobile carrier billing within your mobile application.

All you have to do is to import the library into your Android project and start using our SDK to accept in-app payments. It is quick and easy! We'll guide you through the process here.

How does it work ?

1. The customer can make a purchase, simply by clicking on the buy button inside your application.
2. The Mobiamo SDK is called at this moment and displays a pop up dialog with the payment information.
3. User confirms the payment simply by clicking on the “Buy” button.
4. The payment is completed and your callback function is triggered to handle its result. We will also notify your backend about this event.

Requirements

Android 2.2 (API Level 8) and above.

Credentials

Your mobile integration requires a Project key. You can obtain these Paymentwall API credentials in the application settings of your Merchant Account at paymentwall.com

Add SDK to your project

Our SDK is delivered as a JAR package so just drop it into your project.

Modify AndroidManifest.xml

Required permission

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.SEND_SMS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Add a custom permission

<!-- Define your own permission to protect payment broadcast -->
<permission
    android:name="${applicationId}.mobiamo.PAYMENT_BROADCAST_PERMISSION"
    android:label="Request for sending broadcast to Mobiamo"
    android:protectionLevel="signature" />

<!-- "signature" permission granted automatically by system, without notifying user. -->
<uses-permission android:name="${applicationId}.mobiamo.PAYMENT_BROADCAST_PERMISSION" />

Please note that, ${applicationId} placeholder works with Android Studio. For Eclipse, please change it to your application package name.

Add required activity

<activity
    android:name="com.paymentwall.sdk.mobiamo.MobiamoDialogActivity"
    android:configChanges="orientation|keyboardHidden|screenSize"
    android:theme="@style/Theme.AppCompat.Light.Dialog" >
</activity>

Add required Broadcast Receiver

<receiver
    android:name="com.paymentwall.sdk.mobiamo.MobiamoBroadcastReceiver"
    android:exported="false"
    android:permission="${applicationId}.mobiamo.PAYMENT_BROADCAST_PERMISSION">
    <intent-filter>
        <action android:name="com.paymentwall.mobiamosdk.SENT_SMS_ACTION"></action>
    </intent-filter>
</receiver>

Please note that, ${applicationId} placeholder works with Android Studio. For Eclipse, please change it to your application package name.

Accept your first payment

Required classes

import com.paymentwall.sdk.mobiamo.MobiamoPayment;
import com.paymentwall.sdk.mobiamo.MobiamoResponse;
import com.paymentwall.sdk.mobiamo.utils.Const;
import com.paymentwall.sdk.mobiamo.utils.ResponseCode;

Create Mobiamo request

You need to provide your project key and set your product's id and name. Both can be strings up to 255 characters. You should also specify the user identifier; it can be your internal in-app ID of the user or any other identifier. See example below:

MobiamoPayment request = new MobiamoPayment();
request.setApplicationKey(YOUR_APPLICATION_HERE);
request.setProductId("1001");
request.setProductName("Golden helmet");
request.setUid(YOUR_USER_ID_HERE);

Payment Flow

Choose among these 2 below flows. After completing based on our introduction, please contact our PW team to enable Mobiamo pinless API for your project.

Price point selection

On the payment popup the user will be able to choose which price point they prefer to complete the payment with. In other words, you can provide the user with predetermined price options (i.e you can offer 100 credits for 1 USD or 1000 credits for 10 USD). Please note that the range of price points is limited using mobile payments, so in most cases you can’t set custom values.

All you need to do is create an intent and run the process

Intent intent = MobiamoPayment.createIntent(request, getApplicationContext());
startActivityForResult(intent, MOBIAMO_REQUEST_CODE);

Preselected price point

When you know which exact price you want to be charged (let’s say you’ve cached all available price points) you can force Mobiamo SDK to charge this exact amount. The user will not see the price points selection drop down.

For this case, you need to add additional parameters of amount and currency to the MobiamoRequest:

request.setAmount("1");
request.setCurrency("EUR");

Create an Intent

Create an intent and run the process

Intent intent = MobiamoPayment.createIntent(request, getApplicationContext());
startActivityForResult(intent, MOBIAMO_REQUEST_CODE);

Defining the country

If you need to define the ISO alpha-2 country code of the SIM card, use the code below:

TelephonyManager tm = (TelephonyManager) getApplicationContext().getSystemService(Context.TELEPHONY_SERVICE);
String mCountry = tm.getSimCountryIso().toUpperCase(Locale.US);

Result handling

You can handle payment results by defining your callback function. We recommend syncing up with your server at this stage to sync up user's balance, confirm purchased item etc. See the example:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == MOBIAMO_REQUEST_CODE) {
        if (resultCode == ResponseCode.ERROR) {
            Toast.makeText(MainActivity.this, "ERROR", Toast.LENGTH_LONG).show();
        } else if (resultCode == ResponseCode.FAILED) {
            Toast.makeText(MainActivity.this, "FAILED", Toast.LENGTH_LONG).show();
        } else if (resultCode == ResponseCode.CANCEL) {
            Toast.makeText(MainActivity.this, "CANCEL", Toast.LENGTH_LONG).show();
        } else if (resultCode == ResponseCode.SUCCESSFUL) {
            Toast.makeText(MainActivity.this, "SUCCESSFUL", Toast.LENGTH_LONG).show();
            if(data!=null) {
                MobiamoResponse response = (MobiamoResponse) data.getSerializableExtra(Const.KEY.RESPONSE_MESSAGE);
                if (response != null && response.isCompleted()) {
                    // Do something with the response
                }
            }
        }
    }
}

ResponseCode values

ResponseCode code can get one of the following values:

• ResponseCode.SUCCESSFUL: user has completed the payment
• ResponseCode.ERROR: there's no SIM card installed or network/SSL/parameters error
• ResponseCode.FAILED: the payment happened but it's not successful
• ResponseCode.CANCEL: user has aborted the payment

Server notification handling

After each successful payment we will notify your server about it. We recommend to use this feature as it is the most reliable way to know when the payment went through. Even if your application crashes for some reason, your server will still be notified, so you can sync up later.

Please see pingback processing documentation for more information.

In order to download and install the Mobiamo Android SDK, please contact us at devsupport@paymentwall.com