PAYMILL Android SDK

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

Sample App

View our open source sample / demo app VoucherMill.

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.2.0.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.2.0</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.2.0'
}       

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);
}

Customizing notification.

To ensure that your app does not get killed while the SDK is processing a payment ( or an important task you complete in your Background Listener) we keep the PMService in foreground mode in this time frame. In versions prior 4.3 the foreground notification was not shown to your customer. Unfortunately, since 4.3 Android will always show the notification. To help you customize the appearance, we now let you customize the notification, as well as turn foreground mode completely. Please note, turning off foreground mode effects the reliability of your app.

{
....
PMManager.setForegroundEnabled(true); // turn on the foreground notification (default is true / on)
NotificationBuilder builder = new NotificationBuilder() {
			
			@SuppressWarnings("deprecation")
			@Override
			public Notification getForegroundNotification() {
				// use NotificationCompat.Builder if you target Android < 4
			 	return new Notification.Builder(mContext) 
			         .setContentTitle("Processing payment")
			         .setContentText("My app is processing your payment")
			         .setSmallIcon(R.drawable.ic_launcher)
			         .build();
			}
		};
PMManager.setForegroundNotificationBuilder(builder);
...
}

Release notes

1.2.0

• Added new methods to create transactions and preauthorizations with a payment object.
• Added a Safe Store to securely save payment objects with a user password.
• Added the possibility to turn off or style the foreground notification.

1.1.1

• Mandatory changes in infrastructure

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