SADAD Payment Gateway SDK for Dart - Flutter and Server-Side

Louis Innovations has released a native Dart SDK for SADAD Payment Gateway, enabling Flutter mobile applications and server-side Dart services to process Qatar payments without platform channels or JavaScript bridges. The SDK is published on pub.dev and supports checkout, transaction inquiry, refunds, and asynchronous payment processing with complete null safety.

Installation and Setup

Add the package to your pubspec.yaml:

dependencies:
  sadad_dart: ^1.0.0

The SDK is built with Dart 3 and uses the http package for REST API communication. Initialize the SADAD client with your merchant credentials:

import 'package:sadad_dart/sadad_dart.dart';

final sadad = SadadClient(
  merchantId: 'YOUR_MERCHANT_ID',
  apiKey: 'YOUR_API_KEY',
  environment: SadadEnvironment.sandbox,
);

Flutter Widget Components

The SDK ships with Flutter widgets that integrate directly into your mobile app UI. The SadadCheckoutButton widget initiates a payment flow with a modal dialog:

import 'package:sadad_dart/widgets.dart';

SadadCheckoutButton(
  amount: 350.00,
  currency: 'QAR',
  orderId: 'ORD-2026-045',
  description: 'Consultation Service',
  onSuccess: (transaction) {
    print('Payment completed: ${transaction.id}');
  },
  onError: (error) {
    print('Payment failed: ${error.message}');
  },
)

The widget renders a styled button that opens a WebView to the SADAD hosted payment page when tapped. The WebView intercepts callback URLs to detect payment completion, eliminating the need for deep link configuration.

For custom UI needs, use the SadadWebView widget directly:

SadadWebView(
  paymentUrl: transaction.paymentUrl,
  onCompleted: (result) {
    // result is a PaymentResult with status and transaction ID
  },
)

Server-Side Dart Usage

The SDK is fully functional in server-side Dart applications. Use it in Dart Frog, Shelf, or any Dart HTTP server for backend payment processing:

import 'package:sadad_dart/sadad_dart.dart';

Future<void> handlePaymentRequest(HttpRequest request) async {
  final body = await request.body();
  final payment = PaymentRequest(
    amount: body['amount'],
    currency: 'QAR',
    orderId: body['orderId'],
  );

  try {
    final transaction = await sadad.createTransaction(payment);
    // Store transaction reference and return payment URL
    request.response.write(jsonEncode({
      'paymentUrl': transaction.paymentUrl,
      'transactionId': transaction.id,
    }));
  } on SadadException catch (e) {
    request.response.statusCode = 400;
    request.response.write(jsonEncode({'error': e.message}));
  }
}

Async Payment Processing

The SDK supports both synchronous and asynchronous payment flows. For asynchronous processing, use processPaymentAsync which returns immediately with a pending transaction, then listen for the IPN callback:

final transaction = await sadad.processPaymentAsync(
  amount: 500.00,
  currency: 'QAR',
  orderId: 'ORD-2026-046',
  callbackUrl: 'https://api.yourdomain.com/sadad/ipn',
);

// The transaction is pending. Handle the callback separately.

Error Handling Patterns

The SDK defines a comprehensive error hierarchy. Catch specific exceptions for granular error handling:

try {
  await sadad.createTransaction(payment);
} on AuthenticationException {
  // API key or merchant ID invalid
} on InsufficientFundsException {
  // Customer card has insufficient balance
} on NetworkException {
  // Connection to SADAD gateway failed
} on SadadException catch (e) {
  // Generic SADAD error
  print('Code: ${e.code}, Message: ${e.message}');
}

All error classes extend SadadException and include a machine-readable code and human-readable message field. The SDK also includes a retry utility that automatically retries failed network requests with exponential backoff.

Transaction Inquiry and Refunds

Query transaction status and process refunds using the same client instance:

final status = await sadad.inquireTransaction('TXN-2026-001');
print('Status: ${status.status}'); // SUCCESS, FAILED, PENDING, REFUNDED

final refund = await sadad.processRefund(
  transactionId: 'TXN-2026-001',
  amount: 100.00, // partial refund
);

Frequently Asked Questions

Q: Does the Flutter SDK work on both iOS and Android?

Yes. The SDK uses Flutters platform-agnostic WebView and HTTP packages, so it works identically on iOS and Android. No platform-specific code or native SDKs are required.

Q: Is the SDK compatible with Dart Frog and Serverpod?

Yes. The core SadadClient class has no Flutter dependency, making it usable in any Dart project including Dart Frog, Serverpod, and standalone Dart scripts.

Q: Does the SDK handle Arabic text direction in Flutter?

Yes. The Flutter widgets respect the Directionality widget in your widget tree. When your app is configured for Arabic, the checkout button and error messages render in right-to-left layout automatically.

Q: How do I handle payment timeouts in a mobile app?

Set the timeout parameter on the SadadClient constructor (default is 30 seconds). The SDK will throw a NetworkException if the SADAD gateway does not respond within the timeout. For offline scenarios, queue the payment request and retry when connectivity resumes. Our mobile app development services include offline-first payment architecture guidance.