telr_mobile_payment_sdk 4.3.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.3.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, run pod repo update then re-install. The TelrSDK pod is published from github.com/Telr-PG/telr-sdk-ios and resolves via the standard CocoaPods CDN.

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 / wallet 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, init applies language, debug logging, Samsung Pay, and Google Pay runtime configuration.
• 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,
    googlePayGatewayMerchantId: null,
    googlePayMerchantId: 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)
• Google Pay (Android) — requires Google Pay merchant configuration (see below)
• Samsung Pay (Android) — requires Samsung device and manifest setup (see below)
• Click to Pay — Mastercard, Visa (with 3D Secure)
• 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, googlePayGatewayMerchantId, googlePayMerchantId, 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 at the Samsung Pay Developers portal and obtain a Service ID. Samsung registers the Service ID against your app's package name and signing certificate SHA-256 — debug and release builds have different SHAs, so register both (or use separate sandbox / production Service IDs).
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.22" />
<meta-data android:name="debug_mode" android:value="N" />

• Use spay_sdk_api_level="2.22" exactly — this matches the Samsung Pay SDK bundled inside the Telr SDK. If a future Telr SDK release upgrades it, this value will be updated here.
• debug_mode must be N in production. Set to Y only in development builds — shipping Y to production causes Samsung Pay to behave unpredictably.

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, in supported regions.

Common reasons Samsung Pay does not appear

1. App not registered with Samsung against your package name + signing SHA-256 — the most common cause. Debug and release builds have different SHAs. Use a sandbox Service ID with the debug-keystore SHA and a production Service ID with the release-keystore SHA, or register both SHAs against one Service ID.
2. Device is not Samsung, or Samsung Wallet has no provisioned card — the SDK reports SPAY_NOT_READY and hides the option.
3. Backend did not return order._links.samsungPay.href — confirm with your Telr account manager that Samsung Pay is enabled for your merchant account.
4. Country / region not supported — Samsung Pay is region-locked. The device must be in a supported country.
5. Manifest meta-data missing or wrong version — spay_sdk_api_level must match the value documented above. Filter logcat for SamsungPayRequirements to see validation warnings emitted by the SDK.

Google Pay (Android)

1. Configure Google Pay for your Telr merchant account so the backend order includes order._links.googlePay.href.
2. Initialize the SDK with your Android Google Pay settings:

await TelrSdk.init(
  googlePayGatewayMerchantId: '<YOUR_GATEWAY_MERCHANT_ID>',
  googlePayMerchantId: '<YOUR_GOOGLE_MERCHANT_ID>',
);

Google Pay only appears when the backend enables it and Google Wallet is available and ready on the device.

Click to Pay

Click to Pay appears when your order enables allowedPaymentMethods.type = CLICK_TO_PAY (or order._links.clicktopay.href is present).

• No SDK configuration or merchant registration required. dpaId, acquirer config, and locale come from the order response — Telr's backend owns the network registration.
• The SDK handles consumer recognition, email entry, OTP authentication, saved-card listing, manual card entry, the network DCF challenge UI, and 3DS internally.
• Recognition tokens are persisted on-device per dpaId so returning users skip the email/OTP step on the next session.

No additional Flutter-side configuration is required — the option appears automatically in the payment sheet when the backend enables it.

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