📘

SDK integration: mobileToken required!

This page provides detailed steps on how to add the Android SDK to your project. Please ensure you have reviewed the general Mobile SDK overview before continuing. To start using the Android SDK, make sure your backend can generate a mobileToken via the init endpoint. With this token, your Android app can initialize and launch transactions.

Integration

For Android projects, you can link the repo and dependencies via Gradle as demonstrated below.

repositories {
	...
	maven { url 'https://datatrans.jfrog.io/artifactory/mobile-sdk/' }
}

dependencies {
	...
    implementation 'ch.datatrans:android-sdk:3.9.1' // Check release notes for latest version
}

Call the library with your mobile token to start a transaction. You can optionally specify further options and pass tokens for fast checkouts with our provided classes. Below is an example of the suggested minimum options to start a transaction with Android (Kotlin, Java). Please read our detailed class description for Android to discover more initialization options.

val transaction = Transaction(mobileToken)
transaction.listener = this // this refers to Android's Activity
transaction.options.isTesting = true
transaction.options.useCertificatePinning = true
TransactionRegistry.startTransaction(this, transaction)

Transaction transaction = new Transaction(mobileToken);
transaction.setListener(this); // this refers to Android's Activity
transaction.getOptions().setTesting(true);
transaction.getOptions().setUseCertificatePinning(true);
TransactionRegistry.INSTANCE.startTransaction(this, transaction);

If you are building an Instant app, you may exclude specific packages that are not required in your project. This will depend on your payment methods and flows. Please reach out to our support if you are unsure about what packages you can exclude.

dependencies {
	...
	implementation ('ch.datatrans:android-sdk:3.9.0') {  // Check release notes for latest version
		exclude group: 'io.card', module: 'android-sdk'
	}
}

The table below lists all the dependencies which can be excluded. Do not exclude a dependency if it is required by a payment method you included in your init request.

Additional requirements for Android

If you are integrating PayPal you must add various entries to your app manifest. You will run into technical issues if you do not define the requirements below.

For PayPal payments, an external web process is used. After this web process has finished, a callback to your app is issued. In order to receive this callback, you need to define the Datatrans relay activity with an intent filter in your AndroidManifest.xml for a defined scheme. Keep in mind that the URI scheme must be unique to the shopping app and the activity. Do not use actual protocols or file types such as http, mailto, pdf etc., or generic names such as ticket. An example would be the package name extended by an identifier dtsdk.

<activity
	android:name="ch.datatrans.payment.ExternalProcessRelayActivity"
	android:launchMode="singleTask"
	android:enabled="false"
	android:theme="@android:style/Theme.Translucent.NoTitleBar">
	<intent-filter>
		<action android:name="android.intent.action.VIEW" />
		<category android:name="android.intent.category.DEFAULT" />
		<category android:name="android.intent.category.BROWSABLE" />
		<data android:scheme="your.package.name.dtsdk" />
	</intent-filter>
</activity>

If you are processing Twint, PostFinance Card, or PayPal please make sure to define your app callback scheme in the transaction options, as this is required to properly redirect users back to your app.

transaction.options.appCallbackScheme = "your_scheme"

transaction.getOptions().setAppCallbackScheme("your_scheme");

To offer Klarna as a payment method, you must manually add the repository and dependency to your build gradle. This is currently the only payment method that requires you to do this manually.

repositories {
    ...
    maven { url 'https://x.klarnacdn.net/mobile-sdk/' }
}

dependencies {
    ...
    implementation 'com.klarna.mobile:sdk:2.7.1'
}

After the transaction

After the transaction has been completed, you can refer to the class TransactionSuccess that will return the details of the transaction, including the payment method, the transaction unique identifier, and the token if one was created. If the transaction failed, you will have to refer to the class TransactionError for further details instead. You may also implement TransactionListener to be notified when a transaction is successfully finalized, encounters an error, or is canceled by the user. We will also return the transaction information to your defined webhook, as defined here.

Styling the theme

You can style various colors in our Android SDK to match your corporate identity. Check the graphic below to see what color properties can be defined. On Android, set theme options in your project's color XML resource file, typically colors.xml. Use the color key names as defined in the table below. Don't forget to set colors for Android's light and dark theme (values & values-night).