PAYMILL Android SDK

The Android SDK provides a flexible and easy to integrate payment solution for your Android applications.

Sample App

Our open source sample / demo app VoucherMill is available for download on Google Play.

Getting started

• Start with the SDK guide.
• Install the latest release.
• If you want to create transaction and preauthorizations directly from within your app, install the PAYMILL mobile app.
• Check the sample / demo app VoucherMill for a showcase and stylable payment screens.
• Check the full API documentation.

Requirements

Android 2.2 (API Level 8).

Installation

• Eclipse users add the androi-sdk-1.1.jar to their libs/ folder.
• Maven users add this dependency to their pom.xml:

<dependency>
	<groupId>com.paymill.android</groupId>
	<artifactId>android-sdk</artifactId>
	<version>1.1</version>
</dependency>         

• Gradle / Android Studio / IntelliJ add following dependency to their build.gradle:

apply plugin: 'android'

repositories {
    mavenCentral()
}

dependencies {
   compile 'com.paymill.android:android-sdk:1.1'
}       

You will also have to add the following service definition inside the application tag in your AndroidManifest.xml:

 <!-- paymill sdk service -->
 <service android:name="com.paymill.android.service.PMService"
         android:enabled="true" android:exported="false">
 </service> 

If you haven't already, you will need to add the INTERNET permission to your AndroidManifest.xml:

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

Working with the SDK

Listeners

The class PMManagerexposes all the functionalities of the SDK trough static methods. The methods are asynchronous, return immediately and are thread-safe. Before calling a method, you should register a listener to receive the result. There are two types of listeners:

• Foreground Listeners can be added with the addListener() methods. Their callbacks are executed on the UI Thread and it is safe to modify UI elements from the callbacks.
• A BackgroundListener is set with the setBackgroundListener() method. The callbacks are executed on a separate Thread. Use if for long running and/or critical operations. The execution of the callback holds the PMService in foreground mode, so make sure you return from the callback method at some point.

A typical app may take advantage of both listeners, using a foreground listener to inform the user of sucessfull transaction, while using the background listener for network communication, database queries, etc.

Important: The SDK holds a strong references to both types of listeners. To not leak resources, make sure you remove listeners when you don't need them any longer. A good practice is to add your listener onCreate() and remove it onDestroy().

PMMethod, PMParams and PMFactory

A PMPaymentMethod object contains the credit card or bank account information of a customer. A PMPaymentParams object contains the parameters of a payment - amount, currency, description. Both must always be created with the PMFactoryclass.

Generate a token

Create PMPaymentMethod and PMPaymentParams, add listeners and call PMManager.generateToken() with your PAYMILL public key and mode.

protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  PMManager.addListener(listener);
}

PMGenerateTokenListener listener = new PMGenerateTokenListener() {
  public void onGenerateTokenFailed(PMError error) {
    Log.e("PM", "Error:" + error.toString());
  }

  public void onGenerateToken(String token) {
    Log.d("PM", "Token:" + token);
  }
};

public void test() {
  // the payment method ( cc or dd data)
  PMPaymentMethod method = PMFactory.genCardPayment("Max Mustermann", "4111111111111111", "12", "2015", "1234");
  // the payment parameters (currency, amount, description)
  PMPaymentParams params = PMFactory.genPaymentParams("EUR", 100, null);
  PMManager.generateToken(getApplicationContext(), method, params, PMService.ServiceMode.TEST, "yourpublickey");
}

protected void onDestroy() {
  super.onDestroy();
  PMManager.removeListener(listener);
}

Create a transaction

To create transactions and preauthorizations directly from the SDK you first need to install the Mobile App. In the code you will have to initialize the SDK, by calling [PMManager.init()](http://paymill.github.io/paymill-android/docs/sdk//reference/com/paymill/android/service/PMManager.html#init(android.content.Context, com.paymill.android.service.PMService.ServiceMode, java.lang.String, com.paymill.android.listener.PMBackgroundListener, java.lang.String) method with your PAYMILL public key and mode.

// init the sdk as soon as possible
PMManager.init(getApplicationContext(), PMService.ServiceMode.TEST, "yourpublickey",null, null);
......
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  PMManager.addListener(listener);
}
PMTransListener listener= new PMTransListener() {
  public void onTransactionFailed(PMError error) {
    Log.e("PM", "Error:" + error.toString());
  }

  public void onTransaction(Transaction transaction) {
    Log.d("PM", "Transaction:" + transaction.getId());
  }
};
public void test() {
  // the payment method ( cc or dd data)
  PMPaymentMethod method = PMFactory.genCardPayment("Max Mustermann", "4111111111111111", "12", "2015", "1234");
  // the payment parameters (currency, amount, description)
  PMPaymentParams params = PMFactory.genPaymentParams("EUR", 100, null);
  // add the listener
  PMManager.addListener(listener);
  // trigger the transaction
  PMManager.transaction(getApplicationContext(), method, params, false);
}
protected void onDestroy() {
  super.onDestroy();
  PMManager.removeListener(listener);
}

Release notes

1.1

• Added new method to generate Payments using IBAN and BIC in the PMFactory .
• Generating a token is now also possible without PMParams (using the new methods or just replacing with null).

• Improved error handling and added additional BRIDGE error type in PMError. You can use this to give the user conrecte information, why his card is rejected.

1.0

• First live release.
• Added the possiblity to generate tokens without initializing the SDK. The method can be used exactly like the JS-Bridge and does not require extra activation for mobile.
• Added getVersion for the SDK.

• Bug fixes