Core Concepts

This SDK follows a clean, layered architecture with DI and clear error semantics.

Dependency Injection

• Uses get_it and injectable to wire repositories and services.
• Initialize once with MindPaystack.init(config). Services are resolved with the same PaystackConfig.

final paystack = MindPaystack.instance;
final txService = paystack.transaction;      // TransactionService
final chargeService = paystack.charge;       // ChargeService
final planService = paystack.plan;           // PlanService
final subscriptionService = paystack.subscription; // SubscriptionService
final pmService = paystack.paymentMethods;   // PaymentMethodService
final channelService = paystack.paymentChannel; // PaymentChannelService

Networking

• Built on dio with interceptors:
  • Request enrichment: request IDs, idempotency, SDK metadata, environment
  • Authentication: Bearer header (uses secret key by default)
  • Retry: exponential backoff and jitter
  • Error mapping: converts Dio errors to MindException
  • Logging: structured logs configurable by LogLevel

Errors

All SDK methods throw MindException with:

• message, code
• category (network, authentication, validation, server, unknown)
• severity (info, warning, error, fatal)
• metadata (requestId, statusCode, url, etc.)

try {
  await paystack.transaction.verifyTransaction('ref');
} on MindException catch (e) {
  // e.category, e.isRetriable, e.displayMessage
}

Amounts and currency

• Amounts are in the lowest denomination (e.g., kobo for NGN).
• Default currency is NGN; override per call or via config.

Models and typing

Responses are strongly typed using freezed data models across features.

Core Features

The SDK provides comprehensive payment and subscription management capabilities:

Transactions The primary way to accept one-time payments. Transactions represent a customer’s intent to pay and can be in various states (pending, success, failed, abandoned).

Subscription Plans
Reusable billing structures for recurring payments. Plans define the amount, billing frequency, and other settings for subscriptions.

Subscriptions Active recurring billing relationships between customers and plans. Handle the entire subscription lifecycle from creation to management.

Direct Charges For advanced use cases where you need complete control over the payment flow, including handling PIN, OTP, and other authentication methods.