SofizPay SDK for Dart #

🚀 A powerful Dart SDK for Stellar blockchain DZT token payments

📋 Table of Contents #

• Overview
• Features
• Installation
• Quick Start
• API Reference
• Usage Examples
• Real-time Transaction Monitoring
• Error Handling
• Best Practices
• Contributing
• Support
• License

🌟 Overview #

SofizPay SDK is a powerful Dart library for Stellar blockchain DZT token payments with real-time transaction monitoring and comprehensive payment management.

Key Benefits:

• 🔐 Secure Stellar blockchain integration
• ⚡ Real-time transaction monitoring
• 🎯 Simple, intuitive API
• 📱 Cross-platform support

✨ Features #

• ✅ Send DZT Payments: Secure token transfers with memo support
• ✅ Transaction History: Retrieve and filter transaction records
• ✅ Balance Checking: Real-time DZT balance queries
• ✅ Transaction Search: Find transactions by memo or hash
• ✅ Real-time Streams: Live transaction monitoring with callbacks
• ✅ CIB Transactions: Create CIB bank transactions for deposits
• ✅ Error Handling: Robust error management and reporting

📦 Installation #

Add SofizPay SDK to your pubspec.yaml:

dependencies:
  sofizpay_sdk_dart: ^1.0.6

Then run:

dart pub get

For Flutter projects:

flutter pub get

🚀 Quick Start #

1. Import the SDK #

import 'package:sofizpay_sdk_dart/sofizpay_sdk_dart.dart';

2. Initialize the SDK #

final sofizPay = SofizPaySDK();

3. Your First Payment #

// Send a DZT payment
final result = await sofizPay.submit(
  secretkey: 'YOUR_SECRET_KEY',
  destinationPublicKey: 'DESTINATION_PUBLIC_KEY',
  amount: 10.0,
  memo: 'Payment for services',
);

if (result.success) {
  print('Payment successful! TX: ${result.transactionHash}');
} else {
  print('Payment failed: ${result.error}');
}

📚 API Reference #

submit() - Send Payment #

final result = await sofizPay.submit(
  secretkey: 'YOUR_SECRET_KEY',
  destinationPublicKey: 'DESTINATION_PUBLIC_KEY', 
  amount: 10.0,
  memo: 'Payment memo',
);

getDZTBalance() - Check Balance #

final result = await sofizPay.getDZTBalance(secretkey);
print('Balance: ${result.data!['balance']} DZT');

getTransactions() - Transaction History #

final result = await sofizPay.getTransactions(secretkey, limit: 50);

startTransactionStream() - Real-time Monitoring #

await sofizPay.startTransactionStream(secretkey, (transaction) {
  print('New ${transaction['type']}: ${transaction['amount']} DZT');
});

makeCIBTransaction() - CIB Transaction #

final result = await sofizPay.makeCIBTransaction({
  'account': 'ACCOUNT_NUMBER',
  'amount': 100.0,
  'full_name': 'John Doe',
  'phone': '+1234567890',
  'email': 'john@example.com',
  'memo': 'Payment for order',
  'return_url': 'https://your-site.com/callback',
});

Other Methods #

• getPublicKey() - Extract public key from secret key
• searchTransactionsByMemo() - Search transactions by memo
• getTransactionByHash() - Get transaction by hash

🔄 Real-time Transaction Monitoring #

// Start monitoring
await sofizPay.startTransactionStream(secretkey, (transaction) {
  print('New ${transaction['type']}: ${transaction['amount']} DZT');
  if (transaction['type'] == 'received') {
    handleIncomingPayment(transaction);
  }
});

// Check status
final status = await sofizPay.getStreamStatus(secretkey);

// Stop monitoring
await sofizPay.stopTransactionStream(secretkey);

💡 Usage Examples #

Complete Payment Flow #

import 'package:sofizpay_sdk_dart/sofizpay_sdk_dart.dart';

void main() async {
  final sofizPay = SofizPaySDK();
  const secretKey = 'YOUR_SECRET_KEY';
  
  try {
    // Check balance
    final balanceResult = await sofizPay.getDZTBalance(secretKey);
    final balance = balanceResult.data!['balance'];
    print('Balance: $balance DZT');
    
    // Send payment
    if (balance >= 10.0) {
      final result = await sofizPay.submit(
        secretkey: secretKey,
        destinationPublicKey: 'DESTINATION_PUBLIC_KEY',
        amount: 10.0,
        memo: 'Service payment',
      );
      
      if (result.success) {
        print('Payment successful: ${result.transactionHash}');
      }
    }
  } finally {
    sofizPay.dispose();
  }
}

Payment Monitoring System #

class PaymentMonitor {
  final SofizPaySDK _sdk = SofizPaySDK();
  
  Future<void> startMonitoring(String secretKey) async {
    await _sdk.startTransactionStream(secretKey, (transaction) {
      if (transaction['type'] == 'received') {
        print('💰 Payment received: ${transaction['amount']} DZT');
        print('From: ${transaction['from']}');
        // Process payment...
      }
    });
  }
  
  void dispose() => _sdk.dispose();
}

CIB Transaction Example #

class CIBPaymentProcessor {
  final SofizPaySDK _sdk = SofizPaySDK();
  
  Future<void> processCIBTransaction({
    required String account,
    required double amount,
    required String fullName,
    required String phone,
    required String email,
    String? memo,
    String? returnUrl,
  }) async {
    try {
      final result = await _sdk.makeCIBTransaction({
        'account': account,
        'amount': amount,
        'full_name': fullName,
        'phone': phone,
        'email': email,
        'memo': memo ?? 'CIB Transaction',
        'return_url': returnUrl,
        'redirect': 'no',
      });
      
      if (result.success) {
        print('CIB Transaction created successfully');
        print('URL: ${result.data!['url']}');
        // Handle successful response
      } else {
        print('CIB Transaction failed: ${result.error}');
      }
    } catch (error) {
      print('Error: $error');
    }
  }
}

⚠️ Error Handling #

All methods return structured response objects:

final result = await sofizPay.submit(/* parameters */);

if (result.success) {
  print('Success: ${result.transactionHash}');
} else {
  print('Error: ${result.error}');
}

Common errors:

• 'Secret key is required.'
• 'Valid amount is required.'
• 'Destination public key is required.'

🏆 Best Practices #

// ✅ Store secret keys securely (use secure storage in production)
// ✅ Always check result.success before accessing data
// ✅ Dispose SDK instances when done: sofizPay.dispose()
// ✅ Validate inputs before API calls
// ✅ Use appropriate transaction limits for better performance

🤝 Contributing #

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

# Development setup
git clone https://github.com/kenandarabeh/sofizpay-sdk-dart.git
cd sofizpay-sdk-dart
dart pub get
dart test

📞 Support #

• 📖 Documentation
• Report Issues
• � Discussions
• ⭐ Star the Project

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

• Built on the robust Stellar Network
• Powered by stellar_flutter_sdk
• Inspired by the growing DeFi ecosystem