telr_mobile_payment_sdk 4.1.0

Flutter plugin that wraps Telr native iOS/Android SDKs via platform channels to present the payment UI.

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

1. Update the version in pubspec.yaml and run:

flutter clean
flutter pub get

2. For iOS, update pods to the latest TelrSDK:

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

iOS setup

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

platform :ios, '15.1'

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

2. 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

1. Ensure repositories in android/settings.gradle:

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

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

android {
  compileSdkVersion 34

  defaultConfig {
    minSdkVersion 21
    targetSdkVersion 34
  }
}

3. 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)

1. Apple Developer Portal: Enable Apple Pay for your App ID and create a Merchant Identity Certificate under Certificates, Identifiers & Profiles > Identifiers > Merchant IDs.
2. Xcode: Open ios/Runner.xcworkspace, add the Apple Pay capability to the Runner target, and select your Merchant ID.
3. 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)

1. Samsung Developers Portal: Register as a Samsung Pay partner and obtain a Service ID.
2. 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.

3. 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.

Links

• Package on pub.dev: telr_mobile_payment_sdk
• Example app: see example/

License

MIT