PWLocal Android SDK§

Introduction§

Do you need to have an ability to accept payments from mobile users in different countries, considering which payment methods fit best? PWLocal is a global payment gateway that makes it easy to accept payments from customers in more than 200 countries with 100+ alternative payment options. PWLocal Android SDK will become a native part of your application, it eliminates the necessity to open a web browser for payments, as a result you will receive a higher conversions rate. All you have to do is 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 clicks on the “Buy” button inside your application.
2. The PWLocal SDK is called at this moment and opens application dialog with the list of payment systems.
3. User chooses a payment system and clicks on “Buy”. After it, a new application dialog opens. It would be a "thank you" screen or a dialog for providing payment details, such as credit card number, if needed.
4. The payment is completed and your callback function is triggered to handle its result. Your backend will be also notified about it.

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§

Our SDK is delivered as a JAR package so just drop it into your project. It also requires android-support-v4.jar, if your project doesn’t have it, please add one.

Modify your AndroidManifest.xml§

Add required permission§

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

Add required activity§

<activity
    android:name="com.paymentwall.sdk.pwlocal.ui.PwLocalActivity"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:theme="@android:style/Theme.Translucent" />

First payment§

Import§

import com.paymentwall.sdk.pwlocal.message.*;
import com.paymentwall.sdk.pwlocal.ui.PwLocalActivity;
import com.paymentwall.sdk.pwlocal.utils.Key;
import com.paymentwall.sdk.pwlocal.utils.PaymentMethod;
import com.paymentwall.sdk.pwlocal.utils.ResponseCode;
import com.paymentwall.sdk.pwlocal.utils.MessageUtils;

Create a request§

We have 2 types of PWLocal payment request: LocalDefaultRequest and LocalFlexibleRequest We support 3 API type: ApiType.VIRTUAL_CURRENCY, ApiType.DIGITAL_GOODS, ApiType.CART For more information, please refer to: https://www.paymentwall.com/en/documentation/Digital-Goods-API/710

Defined request§

We defined 2 types of request: LocalDefaultRequest and LocalFlexibleRequest. You can simply use setters to set required parameters. Please note that all the parameters are changed from under_score to camelCase format. Your signature will be calculated automatically if signVersion and secret are set.

Example§

LocalDefaultRequest request = new LocalDefaultRequest();
request.setKey(PROJECT_KEY);
request.setUid(USER_ID);
request.setWidget(WIDGET_TYPE);
request.setApiType(API_TYPE);
request.setSecretKey(SECRET_KEY);
request.setSignVersion(3);
request.setMobileDownloadLink(YOUR_MOBILE_APP_DOWNLOAD_LINK);

Custom request§

If our defined request does not match your need. We also supported Map-like query. It follows the parameters in https://www.paymentwall.com/en/documentation/Digital-Goods-API/710. Most of the parameters are already defined in Const.P class. Your signature will be calculated automatically if signVersion and secret are set.

Example§

CustomRequest request = new CustomRequest();
request.put(Const.P.KEY, PROJECT_KEY);
request.put(Const.P.WIDGET, "m2_1");
request.put(Const.P.EVALUATION, "1");
request.put(Const.P.UID, "testuser");
request.put(Const.P.AG_EXTERNAL_ID, "testitem");
request.put(Const.P.AG_NAME, "Test item");
request.put(Const.P.CURRENCYCODE, "USD");
request.put(Const.P.AMOUNT, "0.5");
request.put(Const.P.AG_TYPE, "fixed");
request.setMobileDownloadLink(YOUR_MOBILE_APP_DOWNLOAD_LINK);
request.setSecretKey(SECRET_KEY);
request.setSignVersion(3);

Widget signature§

Using Widget signature secures your widget and prevents unauthorized access.

Auto signing (unsecured)§

Normally, autoSigned is turned off. You can turn it on by setting a secretKey. Your widget call will be automatically signed.

request.setSignVersion(3);
request.setSecretKey("Your Secret Key");

By using this method, your secretKey can be compromised against reverse-engineering. Please consider storing it in a secured place.

Manual signing§

Storing secretKey on your own backend lower your risk of exposing it. Signing your request remotely is recommended to secure your project. Please note that some parameters are added by default. Use this method to get all required parameters for signing

/// default parameters
Map<String,String> defaultParameters = MessageUtils.getDefaultParameters();

Or

// do this after setting all parameters
Map<String,String> generatedParameters = MessageUtils.getDefaultParameters(request);

Sorting parameters alphabetically (ie: using a TreeMap) before signing is required to work with PWLocal SDK.

Defined request§

request.setSignVersion(3);
request.setSign("Signature Value");

Custom request§

request.setSignVersion(3);
request.put(Const.P.SIGN,"Signature Value");

Please see Signature calculation for signing algorithm.

User Profile API§

PWLocal SDK supports User Profile API. Setting UserProfile can be done by simply put it in a Defined Request as following

UserProfile userProfile = new UserProfile();
//Please set user email and registration date here
userProfile.setEmail(USER_EMAIL);
userProfile.setRegistrationDate(REGISTRATION_DATE);
request.setUserProfile(userProfile);

Or to a Custom request

UserProfile userProfile = new UserProfile();
//Please set user email and registration date here
userProfile.setEmail(USER_EMAIL);
userProfile.setRegistrationDate(REGISTRATION_DATE);
request.putAll(userProfile.toParameters());

Start PWLocal dialog§

Defined request§

Intent intent = new Intent(getApplicationContext(), PwLocalActivity.class);
//PaymentMethod.PW_LOCAL_DEFAULT or PaymentMethod.PW_LOCAL_FLEXIBLE
intent.putExtra(Key.PAYMENT_TYPE, PaymentMethod.PW_LOCAL_DEFAULT);
intent.putExtra(Key.PWLOCAL_REQUEST_MESSAGE, (Parcelable) request);
startActivityForResult(intent, PwLocalActivity.REQUEST_CODE);

Custom request§

Intent intent = new Intent(getApplicationContext(), PwLocalActivity.class);
intent.putExtra(Key.CUSTOM_REQUEST_TYPE, ApiType.DIGITAL_GOODS);
intent.putExtra(Key.CUSTOM_REQUEST_MAP, request);
startActivityForResult(intent, PwLocalActivity.REQUEST_CODE);

Handle result§

You can handle payment results by defining your callback function. We recommend syncing up with your server at this point 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==PwLocalActivity.REQUEST_CODE) {
    switch (resultCode) {
      case ResponseCode.CANCEL:
        break;
      case ResponseCode.ERROR:
        String errorMessage = data.getStringExtra(Key.SDK_ERROR_MESSAGE);
        break;
      case ResponseCode.SUCCESSFUL:
        break;
      default:
        break;
    }
  }
}

resultCode code can have one of the following values:

ResponseCode.SUCCESSFUL: the user has completed the payment

ResponseCode.CANCEL: the user has aborted the payment

ResponseCode.ERROR: the payment cannot be done due to some error:

• Network error
• Invalid supplying request

If widget call request is set, the request is also returned via data

Defined request§

if (data != null && data.hasExtra(Key.PWLOCAL_REQUEST_MESSAGE)) {
    LocalRequest request = data.getParcelableExtra(Key.PWLOCAL_REQUEST_MESSAGE);
}

Custom request§

if (data!=null && data.hasExtra(Key.CUSTOM_REQUEST_MAP)) {
    CustomRequest parameters = data.getParcelableExtra(Key.CUSTOM_REQUEST_MAP);
}

Payment Status API utils§

Our SDK also supports Payment Status API.

Create PaymentStatusRequest§

Unsigned call

PaymentStatusRequest request = new PaymentStatusRequest.Builder().setQuery(
                        PROJECT_KEY, // your project key
                        USER_ID, // user id
                        AG_EXTERNAL_ID) // external id of the product
                        .build();

Signed call

PaymentStatusRequest request = new PaymentStatusRequest.Builder().setQuery(
                        PROJECT_KEY, // your project key
                        USER_ID, // user id
                        AG_EXTERNAL_ID // external id of the product
                        SECRET_KEY, // project secret key
                        3) // sign version
                        .build();

Unsigned call can be enabled by request. Please inform our bizdev. Please note that, enabling unsigned Payment Status API call can make your information less secured.

Get payment status§

PaymentStatusUtils.getPaymentStatus(request, new PaymentStatusCallback(){
    @Override
    public void onError(Exception e) {
    // Handle error
    }

    @Override
    public void onSuccess(List<PaymentStatus> result) {
    // Handle the result
    }
});

Payment Status in activityResult§

Experimental feature We also return PaymentStatus in activityResult if your call meets 4 following requirements:

• It's a flexible widget call (custom or defined request)
• It has agExternalId, uid and projectKey set
• Payment Status extra is enable in request Intent

    intent.putExtra(Key.ENABLE_PAYMENT_STATUS, true);

• There is only 1 returned Payment Status

The returned Payment Status can be get from onActivityResult callback

Bundle paymentStatusBundle = data.getBundleExtra(Key.RESULT_PAYMENT_STATUS);
if (paymentStatusBundle != null && paymentStatusBundle.containsKey(Key.PAYMENT_STATUS_IS_SUCCESSFUL)) {
    boolean successful = paymentStatusBundle.getBoolean(Key.PAYMENT_STATUS_IS_SUCCESSFUL);
    if (successful) {
        PaymentStatus status = paymentStatusBundle.getParcelable(Key.PAYMENT_STATUS_MESSAGE);
    } else {
        Exception e = (Exception) paymentStatusBundle.getSerializable(Key.PAYMENT_STATUS_EXCEPTION);
}

Pingback 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 use pingback processing documentation for more information.

Appendix§

Proguard configuration§

If Proguard is used, please kindly add these lines to your proguard configuration file

-keep class com.paymentwall.sdk.pwlocal.** { *; }
-dontwarn com.paymentwall.sdk.pwlocal.**

Supported parameters§

Here's the list of supported parameters in defined requests

Common parameters§

LocalDefaultRequest§

LocalFlexibleRequest§

UserProfile§

For more information, please see User Profile API