Flutter

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

No additional Android manifest changes are required.

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'),
    );
  }
}

API Reference

`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});
}

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

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.