Teya PosLink SDK - Flutter Payment Terminal Integration

pub package Flutter Android License

A Flutter plugin that provides access to the Teya PosLink SDK for Android. This plugin allows you to integrate Teya payment terminals into your Flutter applications.

Author: Khizar Rehman

⚠️ Platform Support Notice: This plugin currently supports Android only. iOS support is not available as the Teya SDK does not provide iOS support yet.

Features

  • ✅ Initialize Teya SDK with configuration
  • ✅ Setup PosLink integration
  • ✅ Process card payments
  • ✅ Real-time payment state updates
  • ✅ Cancel payments
  • ✅ Support for multiple currencies (GBP, EUR, USD)
  • ✅ Android support
  • ❌ iOS support (not available - Teya SDK limitation)

📦 Installation

Add this to your package's pubspec.yaml file:

dependencies:
  teya_pos_sdk: ^1.0.5

Then run:

flutter pub get

⚙️ Setup

Android Configuration

  1. Minimum SDK Version

    Ensure your android/app/build.gradle has a minimum SDK version of 24:

    android {
    defaultConfig {
        minSdkVersion 24
    }
}

  1. Permissions

    Add the following permissions to your android/app/src/main/AndroidManifest.xml:

    <uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

🚀 Quick Start Guide

Basic Usage

1. Initialize the SDK

import 'package:teya_pos_sdk/teya_pos_sdk.dart';

final teyaSdk = TeyaSdk.instance;

// Initialize with sandbox configuration
final config = TeyaConfig.sandbox(
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
);

await teyaSdk.initialize(config);

// Check if SDK is ready for UI operations
final uiStatus = await teyaSdk.isReadyForUI();
if (uiStatus['isReady']) {
  await teyaSdk.setupPosLink();
} else {
  print('SDK not ready for UI operations');
}

2. Make a Payment

// Make a payment in GBP
final result = await teyaSdk.makePaymentGBP(
  amountInPounds: 5.50,
);

if (result.isSuccess) {
  print('Payment successful! Transaction ID: ${result.transactionId}');
} else {
  print('Payment failed: ${result.errorMessage}');
}

3. Listen to Payment State Changes

teyaSdk.paymentStateStream.listen((state) {
  print('Payment state: ${state.state}');
  print('Is final: ${state.isFinal}');
  
  if (state.isFinal) {
    switch (state.state) {
      case PaymentState.successful:
        // Handle successful payment
        break;
      case PaymentState.cancelled:
        // Handle cancelled payment
        break;
      case PaymentState.processingFailed:
        // Handle failed payment
        break;
    }
  }
});

4. Check UI Readiness

// Check if the SDK is ready for UI operations before setup
final uiStatus = await teyaSdk.isReadyForUI();
if (uiStatus['isReady']) {
  await teyaSdk.setupPosLink();
} else {
  print('SDK not ready for UI operations');
  print('Has activity: ${uiStatus['hasActivity']}');
  print('Has SDK: ${uiStatus['hasSDK']}');
}

API Reference

TeyaSdk

The main class for interacting with the Teya SDK.

Methods

  • initialize(TeyaConfig config) - Initialize the SDK
  • setupPosLink() - Setup PosLink integration
  • makePayment({required int amount, required String currency, String? transactionId, int? tip}) - Make a payment
  • makePaymentWithMajorUnits({required double amount, required String currency, String? transactionId, double? tip}) - Make a payment with amount in major currency units
  • makePaymentGBP({required double amountInPounds, String? transactionId, double? tipInPounds}) - Make a payment in GBP
  • makePaymentEUR({required double amountInEuros, String? transactionId, double? tipInEuros}) - Make a payment in EUR
  • makePaymentUSD({required double amountInDollars, String? transactionId, double? tipInDollars}) - Make a payment in USD
  • cancelPayment() - Cancel the current payment
  • isReadyForUI() - Check if the SDK is ready for UI operations
  • dispose() - Dispose the SDK and clean up resources

Properties

  • paymentStateStream - Stream of payment state changes
  • isInitialized - Whether the SDK is initialized

TeyaConfig

Configuration for the Teya SDK.

Constructors

  • TeyaConfig({required String teyaIdHostUrl, required String teyaApiHostUrl, required String clientId, required String clientSecret, bool isProduction = false})
  • TeyaConfig.sandbox({required String clientId, required String clientSecret})
  • TeyaConfig.production({required String clientId, required String clientSecret})

PaymentState

Enum representing payment states:

  • new_ - Payment is new
  • inProgress - Payment is in progress
  • pending - Payment is pending
  • successful - Payment was successful
  • cancelled - Payment was cancelled
  • cancelling - Payment is being cancelled
  • processingFailed - Payment processing failed
  • communicationFailed - Communication with terminal failed

PaymentResult

Result of a payment operation.

Properties

  • isSuccess - Whether the payment was successful
  • transactionId - Transaction ID
  • eposTransactionId - ePOS transaction ID
  • finalState - Final payment state
  • errorMessage - Error message if payment failed
  • metadata - Additional metadata

Error Handling

The plugin throws TeyaError exceptions for various error conditions:

try {
  await teyaSdk.makePaymentGBP(amountInPounds: 10.0);
} on TeyaError catch (e) {
  print('Teya error: ${e.code} - ${e.message}');
} catch (e) {
  print('Unexpected error: $e');
}

Troubleshooting

Common Issues

1. SDK Navigation Not Working

If the Teya setup UI opens but navigation doesn't work when clicking buttons:

Solution: Ensure the SDK is ready for UI operations before calling setupPosLink():

// Check UI readiness first
final uiStatus = await teyaSdk.isReadyForUI();
if (!uiStatus['isReady']) {
  print('SDK not ready for UI operations');
  return;
}

await teyaSdk.setupPosLink();

2. Activity Context Not Available

If you get "Activity context is not available" error:

Solution: Make sure you're calling the SDK methods from a Flutter widget that has an active Android activity context. The SDK needs an activity context to display UI.

3. Setup Failed Errors

If setupPosLink() fails:

Solution: Check the Android logs for detailed error information:

flutter logs

Look for logs with the "TeyaSDK" tag for detailed debugging information.

4. Platform Not Supported on iOS

If you get platform not supported errors on iOS:

Solution: This plugin only supports Android. The Teya SDK does not provide iOS support yet.

Example

See the example/ directory inside this plugin for a complete example application demonstrating how to use the plugin.

To run the example:

cd example
flutter pub get
flutter run

Requirements

  • Flutter 3.10.0 or higher
  • Dart 3.0.0 or higher
  • Android API level 24 or higher (iOS not supported)
  • Teya SDK (included in the plugin)

Platform Support

Platform Support Status Notes
Android ✅ Supported Full functionality available
iOS ❌ Not Supported Teya SDK does not provide iOS support

iOS Compatibility

If you try to use this plugin on iOS, you will receive a clear error message:

try {
  await teyaSdk.initialize(config);
} on TeyaError catch (e) {
  if (e.code == TeyaErrorCodes.platformNotSupported) {
    print('iOS is not supported: ${e.message}');
    // Handle iOS not supported case
  }
}

License

This plugin is provided as-is. Please refer to Teya's licensing terms for the underlying SDK.

Support

For issues related to this Flutter plugin, please create an issue in the repository. For Teya SDK specific issues, please contact Teya support.

Libraries

teya_pos_sdk