Overview

Bring secure Telr payments to your Flutter app. The SDK launches the checkout flow, manages the steps behind the scenes, and returns a clear success/failure result so you can ship faster.

Requirements

Flutter: ≥ 3.19 (Dart ≥ 3)
iOS: ≥ 15.1
Android: minSdk ≥ 21, targetSdk ≥ 34
Your backend must return two URLs taken directly from the createOrder API response:
- tokenUrl — value of _links.auth.href
- orderUrl — value of _links.self.href

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  telr_mobile_payment_sdk: ^X.Y.Z

Then install:

flutter pub get

Platform Setup

iOS

Ensure your app targets iOS 15.1 or newer in ios/Podfile:

platform :ios, '15.1'

target 'Runner' do
  use_frameworks! :linkage => :static
end

Install pods:

cd ios && pod install

If CocoaPods cannot find the TelrSDK pod, ensure you have access to Telr’s podspec source as provided by Telr and that your Podfile declares the appropriate source entries. Then run pod repo update and re-install.

Android

Ensure repositories are available in android/settings.gradle:

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
  }
}

Set SDK versions in android/app/build.gradle:

android {
  compileSdkVersion 34

  defaultConfig {
    minSdkVersion 21
    targetSdkVersion 34
  }
}

Initialize on app load (configure language/logging)

Call the SDK initializer early (e.g., in main() before runApp()), especially if you want to set the preferred language or enable debug logging.

import 'package:flutter/widgets.dart';
import 'package:telr_mobile_payment_sdk/telr_mobile_payment_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await TelrSdk.init(
    preferredLanguageCode: 'en',
    debugLoggingEnabled: true,
    samsungPayServiceId: null,
    samsungPayMerchantId: null,
  );
  runApp(const MyApp());
}

Usage

import 'package:telr_mobile_payment_sdk/telr_mobile_payment_sdk.dart';

Future<void> startCheckout() async {
  try {
    final PaymentResponse result = await TelrSdk.presentPayment(
      'https://merchant.example.com/token',
      'https://merchant.example.com/order',
    );

    if (result.success) {
      // Handle success (e.g., confirm order)
    } else {
      // Handle cancellation/failure using result.message
    }
  } catch (e) {
    // Handle unexpected errors (network, presentation, etc.)
    print('Payment failed unexpectedly: $e');
  }
}

Minimal UI example:

import 'package:flutter/material.dart';
import 'package:telr_mobile_payment_sdk/telr_mobile_payment_sdk.dart';

class PayButton extends StatelessWidget {
  const PayButton({super.key});

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () async {
        try {
          final res = await TelrSdk.presentPayment(
            'https://merchant.example.com/token',
            'https://merchant.example.com/order',
          );
          final msg = res.success
              ? 'Payment successful'
              : 'Payment failed: ${res.message}';
          if (context.mounted) {
            ScaffoldMessenger.of(context)
                .showSnackBar(SnackBar(content: Text(msg)));
          }
        } catch (e) {
          if (context.mounted) {
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(content: Text('Unexpected error: $e')),
            );
          }
        }
      },
      child: const Text('Pay with Telr'),
    );
  }
}

If you need to set the language or other options, initialize once on app load as shown in the Android setup section, then call presentPayment when needed.

API

init (samsungPayMerchantId) → Future<PaymentResponse>
presentPayment(tokenURL, orderURL) → Future<PaymentResponse>
- Presents the Telr payment UI full-screen and resolves when completed.

Types:

class PaymentResponse {
  final bool success;
  final String message;
  const PaymentResponse({required this.success, required this.message});
}

Merchant checklist

Expose HTTPS tokenURL and orderURL from your backend.
Ensure device/emulator can reach both URLs.
Handle the returned result to confirm/cancel the order server-side.

Notes

The payment view is presented full-screen and dismissed automatically when a result is available.
Ensure the provided tokenURL and orderURL are reachable from the device/emulator and use HTTPS.

Troubleshooting

Android: E002 "Unable to register for Activity Result": Ensure initialization happens during app load. Call TelrSdk.init(...) in main() before runApp().
iOS: CocoaPods cannot find TelrSDK
- Ensure the Telr private spec repo or pod source is configured per Telr’s instructions, then run pod repo update and pod install.
iOS: Build fails due to iOS version
- Set platform :ios, '15.1' or newer in Podfile.
Android: minSdk/targetSdk mismatch
- Set minSdkVersion 21, targetSdkVersion 34, compileSdkVersion 34.
Network/HTTP errors
- Verify your backend tokenURL and orderURL endpoints and device/simulator reachability.

Security and compliance

Always use HTTPS and validate server responses; never embed secrets in the app.
Do not log sensitive payment or cardholder data.

Localization

The payment UI follows the underlying native SDK’s language configuration; contact Telr for customization options.