Zettle POS SDK for Flutter

A Flutter wrapper for the Zettle POS SDK on Android and iOS. Supports card payments, refunds, session management, and card reader settings.

Prerequisites

1. A Zettle developer account.
2. iOS 12.0 or higher.
3. Android minSdkVersion 23 or higher.

Installing

Add zettle to your pubspec.yaml:

1. Registered for a Zettle developer account via Zettle.
2. Deployment Target iOS 16.0 or higher.
3. Android minSdkVersion 23 or higher.

import 'package:zettle/zettle.dart';

Android setup

Add the Zettle GitHub Packages Maven repository to your root build.gradle (see sdk-android):

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/iZettle/sdk-android")
            credentials(HttpHeaderCredentials) {
                name "Authorization"
                value "Bearer <YOUR GITHUB TOKEN>"
            }
            authentication {
                header(HttpHeaderAuthentication)
            }
        }
    }
}

Add the OAuth callback activity to your AndroidManifest.xml:

<activity
    android:name="com.izettle.android.auth.OAuthActivity"
    android:launchMode="singleTask"
    android:taskAffinity="@string/oauth_activity_task_affinity"
    android:exported="true">
    <intent-filter>
        <data
            android:host="<redirect url host>"
            android:scheme="<redirect url scheme>" />
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

iOS setup

Add the following to your Info.plist (see sdk-ios):

<key>UISupportedExternalAccessoryProtocols</key>
<array>
    <string>com.izettle.cardreader-one</string>
</array>

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>external-accessory</string>
</array>

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Our app uses bluetooth to find, connect and transfer data with Zettle card reader devices.</string>

<key>NSBluetoothPeripheralUsageDescription</key>
<string>Our app uses bluetooth to find, connect and transfer data with Zettle card reader devices.</string>

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string><your OAuth redirect URI scheme></string>
        </array>
    </dict>
</array>

<key>NSLocationWhenInUseUsageDescription</key>
<string>You need to allow this to be able to accept card payments</string>

Usage

Initialize the SDK

Call init once at app startup:

await Zettle.init(iosClientId, androidClientId, redirectUrl);

Payments

final response = await Zettle.requestPayment(
  ZettlePaymentRequest(
    amount: 10.00,
    reference: 'unique-reference',
    enableLogin: true,
    enableTipping: false,
    enableInstalments: false,
  ),
);

Refunds

final response = await Zettle.requestRefund(
  ZettleRefundRequest(reference: 'payment-reference', refundAmount: 10.00),
);

Session management

await Zettle.login();
await Zettle.logout();
final status = await Zettle.loggedIn();

Card reader settings

Zettle.showSettings();

Testing locally

To run the example app on a device:

1. Set the required environment variables in your shell profile (~/.zshrc or ~/.bashrc):

   export GITHUB_TOKEN=<your-github-pat>          # read:packages scope, for Zettle Maven repo
   export ZETTLE_APP_ID=<your.app.id>              # Android applicationId (optional, defaults to com.ovatu.zettle_example)
   export ZETTLE_REDIRECT_SCHEME=<scheme>           # OAuth redirect scheme (e.g. myapp)
   export ZETTLE_REDIRECT_HOST=<host>               # OAuth redirect host (e.g. callback)

   If using VSCode, restart it after setting these so Gradle inherits them.

2. Set your client IDs and redirect URL in example/lib/main.dart default values, or pass them via --dart-define:

   flutter run \
     --dart-define=ZETTLE_IOS_CLIENT_ID=<ios-client-id> \
     --dart-define=ZETTLE_ANDROID_CLIENT_ID=<android-client-id> \
     --dart-define=ZETTLE_REDIRECT_URL=<scheme>://<host>

3. Run the example app:

   cd example
   flutter run

API reference

Method	Description
Zettle.init(iosClientId, androidClientId, redirectUrl)	Initialize the SDK (call once)
Zettle.isInitialized	Whether the SDK has been initialized
Zettle.login()	Trigger Zettle login
Zettle.logout()	Log out the current session
Zettle.loggedIn()	Check login status
Zettle.requestPayment(request)	Start a card payment
Zettle.requestRefund(request)	Start a refund
Zettle.showSettings()	Open card reader settings