MindPaystack

The Dart-First Paystack SDK

Built from the ground up for Dart and Flutter developers

---

Pure Dart Core • Type-Safe • Production-Ready • Transaction-Focused

Unlike generic API wrappers, MindPaystack is architected specifically for the Dart ecosystem

Documentation • Quick Start • Examples • Contributing

Why MindPaystack?

// Other SDKs: Dynamic types and unclear errors
final response = await http.post(url, body: data);
final result = json.decode(response.body); // Map<String, dynamic>

// MindPaystack: Strongly typed, clean, and predictable
final transaction = await MindPaystack.instance.transaction.initialize(
  InitializeTransactionOptions(
    email: '[email protected]',
    amount: Money.fromCents(50000, Currency.ngn), // Type-safe money handling
  ),
);
// Returns: Resource<TransactionInitialization>

Built for Modern Dart Development

Feature	MindPaystack	Generic HTTP Client
Type Safety	Available - Strongly typed responses	Missing - Dynamic Map<String, dynamic>
Error Handling	Available - Structured MindException hierarchy	Missing - Generic HTTP errors
Dependency Injection	Available - Built-in Injectable support	Missing - Manual setup required
Testing	Available - Mockable services & interfaces	Missing - HTTP mocking complexity
Money/Currency	Available - Dedicated value objects	Missing - Raw integers (error-prone)
Dart Conventions	Available - Follows Dart/Flutter patterns	Missing - Generic API wrapper

---

Quick Start

Installation

For Pure Dart projects (CLI, server, backend):

dart pub add mind_paystack

For Flutter applications:

dart pub add mind_paystack
# Note: mind_paystack_flutter coming soon!

3-Step Integration

Step 1: Initialize the SDK

import 'package:mind_paystack/mind_paystack.dart';

Future<void> main() async {
  // 🔧 One-time setup
  await MindPaystack.initialize(
    PaystackConfig(
      publicKey: 'pk_test_your_public_key',
      secretKey: 'sk_test_your_secret_key',
      environment: Environment.test,
    ),
  );
  
  // 🚀 Ready to use!
  print('MindPaystack initialized successfully!');
}

Step 2: Create a Payment

final sdk = MindPaystack.instance;

try {
  final transaction = await sdk.transaction.initialize(
    InitializeTransactionOptions(
      email: '[email protected]',
      amount: Money.fromCents(50000, Currency.ngn), // ₦500.00
      metadata: {'product_id': '12345'},
    ),
  );
  
  // ✅ Type-safe access to all properties
  print('Payment URL: ${transaction.data.authorizationUrl}');
  print('Reference: ${transaction.data.reference}');
  
} on MindException catch (e) {
  // 🛡️ Structured error handling
  print('Payment failed: ${e.message} (${e.code})');
}

Step 3: Verify Payment

final verification = await sdk.transaction.verify(
  VerifyTransactionOptions(reference: 'your-transaction-reference'),
);

if (verification.data.status == 'success') {
  print('💰 Payment successful!');
  // Fulfill the order
} else {
  print('❌ Payment failed or pending');
}

---

Examples

E-commerce Checkout

class CheckoutService {
  static Future<String?> createPayment({
    required String customerEmail,
    required List<CartItem> items,
  }) async {
    final total = items.fold(0, (sum, item) => sum + item.price);
    final sdk = MindPaystack.instance;
    
    try {
      final result = await sdk.transaction.initialize(
        InitializeTransactionOptions(
          email: customerEmail,
          amount: Money.fromCents(total, Currency.ngn),
          metadata: {
            'order_items': items.map((e) => e.toJson()).toList(),
            'customer_id': await getUserId(),
          },
        ),
      );
      
      return result.data.authorizationUrl;
    } on MindException catch (e) {
      _logger.error('Checkout failed', e);
      return null;
    }
  }
}

Testing with Mocks

class MockTransactionService extends Mock implements ITransactionService {}

void main() {
  group('PaymentService Tests', () {
    late MockTransactionService mockTransaction;
    late PaymentService paymentService;
    
    setUp(() {
      mockTransaction = MockTransactionService();
      // Inject mock via dependency injection
      GetIt.instance.registerSingleton<ITransactionService>(mockTransaction);
      paymentService = PaymentService();
    });
    
    test('should create payment successfully', () async {
      // Arrange
      when(() => mockTransaction.initialize(any()))
          .thenAnswer((_) async => mockTransactionResponse);
      
      // Act
      final result = await paymentService.createPayment(testRequest);
      
      // Assert
      expect(result.isSuccess, true);
      verify(() => mockTransaction.initialize(any())).called(1);
    });
  });
}

---

What Developers Love About MindPaystack

"Finally, a Paystack SDK that feels like it was built by Dart developers, for Dart developers."
— Flutter Developer

"The type safety and error handling saved us hours of debugging. No more dynamic nightmares!"
— Backend Developer

"Injectable integration made testing our payment flows so much cleaner."
— QA Engineer

Perfect For

Use Case	Why MindPaystack Excels
E-commerce Apps	Type-safe money handling, structured error handling
Fintech Platforms	Enterprise-grade architecture, comprehensive testing
SaaS Billing	Transaction management, webhook handling (coming soon)
Banking Apps	Security-first design, audit trails
Mobile Apps	Flutter-core support, with UI components coming soon

---

Package Ecosystem

Package	Platform	Status	Features
mind_paystack	Pure Dart	Available	Core SDK, Transaction APIs
mind_paystack_flutter	Flutter	Coming Soon	UI widgets, platform integration

Platform Support

Platform	Support Level	Package Required
Flutter Mobile	Core Features	mind_paystack
Flutter Web	Core Features	mind_paystack
Flutter Desktop	Core Features	mind_paystack
Dart VM (Server)	Full Support	mind_paystack
Dart CLI Tools	Full Support	mind_paystack

---

Advanced Features

Dependency Injection Ready

@injectable
class PaymentService {
  PaymentService(this._transactionService);
  
  final ITransactionService _transactionService;
  
  Future<PaymentResult> processPayment(PaymentRequest request) async {
    // Fully testable and mockable
  }
}

Type-Safe Money Handling

// Error-prone raw integers
final amount = 50000; // Is this ₦500 or ₦50,000?

// Clear, type-safe money values
final amount = Money.fromCents(50000, Currency.ngn); // Clearly ₦500.00
final naira = Money.fromNaira(500.00); // Alternative constructor

Structured Error Handling

try {
  final result = await sdk.transaction.initialize(request);
} on MindException catch (e) {
  switch (e.category) {
    case ErrorCategory.network:
      _handleNetworkError(e);
    case ErrorCategory.validation:
      _showValidationErrors(e.validationErrors);
    case ErrorCategory.paystack:
      _handlePaystackError(e);
  }
}

---

🗺️ Roadmap

✅ Current Features (Available Now)

• Transaction Management: Initialize, verify, list transactions
• Type-Safe Money Handling: Structured money/currency objects
• Error Handling: Comprehensive MindException system
• Dependency Injection: Built-in Injectable support
• Pure Dart Support: CLI tools, server applications, web

🚧 Coming Soon

• Charge Operations: Direct card charging and tokenization
• Payment Channels: Available payment methods management
• Payment Methods: Customer payment method storage
• Flutter Package: UI widgets and platform integration
• Webhooks: Event handling and verification
• Subscriptions: Recurring billing management

🔮 Future Releases

• Advanced Analytics: Transaction insights and reporting
• Multi-tenant Support: Organization-level configurations
• Offline Capabilities: Queue transactions for later processing
• Enhanced Security: Additional fraud prevention tools

---

Documentation

Resource	Description
Full Documentation	Complete guides and API reference
Getting Started	3-step integration guide
Architecture Guide	Understanding the SDK design
Testing Guide	Mocking and unit testing
Configuration	Environment setup and options

---

Contributing

We welcome and appreciate contributions from developers of all skill levels!

Read our Comprehensive Contributing Guide →

Our detailed contribution guide covers:

• Quick Start - Get up and running in minutes
• Project Structure - Understanding the monorepo architecture
• Development Workflow - Step-by-step contribution process
• Code Standards - Dart/Flutter style guidelines with examples
• Testing Guidelines - TDD approach, mocking, and coverage requirements
• Pull Request Process - Templates, checklists, and review process
• Security Guidelines - Best practices for handling sensitive data
• Development Tools - VS Code settings, Melos commands, Git hooks

Quick Links

I Want To...	Action
Report a Bug	Open an Issue
Request a Feature	Request Feature
Ask Questions	Start a Discussion
Contribute Code	See Contributing Guide

Quick Development Setup

# 1. Fork and clone the repository
git clone https://github.com/Dartmind-OpenSource/mind-paystack.git
cd mind-paystack

# 2. Install Melos and bootstrap packages
dart pub global activate melos
melos bootstrap

# 3. Verify setup
melos run test && melos run analyze

# You're ready to contribute!

New to open source? We're here to help! Check out issues labeled good first issue for beginner-friendly contributions.

---

📄 License

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

---

Made with ❤️ by the Dart community

Star us on GitHub • Follow us on Twitter • Join our Discord

Building the future of payments in Dart