telr_mobile_payment_sdk - Dart API docs

Telr Flutter Payments SDK

Accept Telr payments in your Flutter app with a single call. The SDK presents the Telr checkout, handles the flow, and returns a clear success/failure result.

Requirements

Flutter: ≥ 3.19 (Dart ≥ 3)
iOS: ≥ 15.1
Android: minSdk ≥ 21, targetSdk ≥ 34
Backend: HTTPS tokenURL and orderURL

Install

Add to pubspec.yaml and fetch:

dependencies:
  telr_mobile_payment_sdk: ^4.1.0

flutter pub get

Updating the plugin version

Update the version in pubspec.yaml and run:

flutter clean
flutter pub get

For iOS, update pods to the latest TelrSDK:

cd ios
pod deintegrate
pod install --repo-update
pod update TelrSDK

iOS setup

Set minimum iOS in ios/Podfile and enable static frameworks:

platform :ios, '15.1'

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

Install pods:

cd ios && pod install

If CocoaPods cannot find TelrSDK, ensure Telr’s private/spec source is configured in your Podfile, run pod repo update, then re-install.

Android setup

Ensure repositories 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
  }
}

Optional: initialize on app load (configure language / iOS options)

Call the SDK initializer early (e.g., in main() before runApp()) when you need runtime configuration.

On iOS, init applies language, debug logging, and Apple Pay options.
On Android, the Flutter bridge currently applies language override; other init fields are accepted for API compatibility and may be ignored.
If you do not need runtime configuration, you can call presentPayment(...) directly.

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,
    // iOS-only options (ignored on Android):
    applePayMerchantIdentifier: null, // e.g. 'merchant.com.yourcompany.yourapp'
    applePayButtonType: 'buy',        // optional
    applePayButtonStyle: 'automatic', // optional
  );
  runApp(const MyApp());
}

Supported Payment Methods

The SDK supports the following payment methods (availability is controlled by your Telr account and order configuration):

Credit/Debit Cards — Visa, Mastercard, Amex, mada (with 3D Secure)
Apple Pay (iOS) — requires Merchant Identity setup (see below)
Samsung Pay (Android) — requires Samsung device and manifest setup (see below)
Tabby — Buy Now Pay Later
Tamara — Buy Now Pay Later
STC Bank — direct bank payment

Use

Minimal 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 language or iOS Apple Pay options, initialize once on app load as shown above, then call presentPayment when needed.

API

Methods

init({ preferredLanguageCode, debugLoggingEnabled, samsungPayServiceId, samsungPayMerchantId, applePayMerchantIdentifier, applePayButtonType, applePayButtonStyle }) → Future<PaymentResponse>
- Initializes the SDK bridge and applies supported runtime configuration for the current platform.
presentPayment(tokenURL, orderURL) → Future<PaymentResponse>
- Presents the full Telr payment UI (all payment methods) and resolves when completed.
payWithCard(tokenURL, orderURL) → Future<PaymentResponse>
- Presents a card-only payment form. Use this when building a custom merchant checkout page.
payWithSavedCard(tokenURL, orderURL, savedCard) → Future<PaymentResponse>
- Pays using a previously saved card. The savedCard parameter is a TelrSavedCard object obtained from a prior addCard call.
addCard(tokenURL, orderURL) → Future<AddCardResponse>
- Presents a form to save a card without charging. Returns saved card tokens that can be stored on your backend and used with payWithSavedCard.
getSdkVersion() → Future<String>
- Returns the underlying native SDK version string.

Types

enum TelrPaymentStatus { success, pending, failure, cancelled }

class PaymentResponse {
  final bool success;
  final TelrPaymentStatus status;
  final String message;
  final String? errorCode;
}

class AddCardResponse extends PaymentResponse {
  final String? ref;
  final String? maskedName;
  final List<TelrSavedCard>? savedCards;
}

class TelrSavedCard {
  final String token;
  final String maskedCard;
  final String expiry;
  final String scheme;
  final String? maskedName;
}

Merchant checkout page example

Build a custom checkout page using the individual payment methods:

// 1. Save a card
final addCardResult = await TelrSdk.addCard(tokenURL, orderURL);
if (addCardResult.status == TelrPaymentStatus.success) {
  // Store addCardResult.savedCards on your backend
}

// 2. Pay with a saved card
final result = await TelrSdk.payWithSavedCard(tokenURL, orderURL, savedCard);

// 3. Pay with a new card (card-only form)
final result = await TelrSdk.payWithCard(tokenURL, orderURL);

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.

Apple Pay (iOS)

Apple Developer Portal: Enable Apple Pay for your App ID and create a Merchant Identity Certificate under Certificates, Identifiers & Profiles > Identifiers > Merchant IDs.
Xcode: Open ios/Runner.xcworkspace, add the Apple Pay capability to the Runner target, and select your Merchant ID.
SDK init: Pass your Merchant Identifier:

await TelrSdk.init(
  applePayMerchantIdentifier: 'merchant.com.yourcompany.yourapp',
);

The SDK shows Apple Pay automatically when the device supports it and the user has cards in Wallet.

Samsung Pay (Android)

Samsung Developers Portal: Register as a Samsung Pay partner and obtain a Service ID.
AndroidManifest.xml: Add under the <application> tag in android/app/src/main/AndroidManifest.xml:

<meta-data android:name="spay_sdk_api_level" android:value="2.19" />
<meta-data android:name="debug_mode" android:value="Y" />

Remove or disable debug_mode in production builds.

SDK init: Pass your Service ID:

await TelrSdk.init(
  samsungPayServiceId: '<YOUR_SERVICE_ID>',
);

Samsung Pay only appears on Samsung devices with Samsung Wallet installed and provisioned.

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: Configure Telr spec source, run pod repo update, then pod install.
iOS: Build fails due to iOS version: Set platform :ios, '15.1' or newer.
Android: minSdk/targetSdk mismatch: Use min 21 / target 34 / compile 34.
Network/HTTP errors: Verify backend endpoints and connectivity.

Security

Always use HTTPS; validate server responses.
Never embed secrets in the app or log cardholder data.

License

MIT