Usage Guide

Learn how to use the flutter_epay SDK for seamless payments in your Flutter app.

Getting Started

This guide covers how to use the flutter_epay SDK to initiate and manage payments in your Flutter application.

1. Installing the SDK

Ensure you have installed the SDK as per the Installation Guide. Add the dependency in your pubspec.yaml file:

dependencies:
  flutter_epay: latest_version
  webview_flutter: latest_version

Run:

flutter pub get

2. Importing the Package

import 'package:flutter_epay/flutter_epay.dart';

3. Initializing a Payment

Use the initiatePayment method to start a transaction:

final epay = FlutterEpay();
 
void handlePayment() async {
  try {
    final response = await epay.initiatePayment(amount: 100);
    print("Payment Response: \$response");
  } catch (error) {
    print("Payment Error: \$error");
  }
}

Response Object Structure:

{
    "data": {
        "type": "transaction",
        "id": "1HYS74O4ZV2804SOCOCG",
        "attributes": {
            "amount": "2500",
            "status": "processing",
            "form_url": "https://test.satim.dz/payment/merchants/merchant1/payment_fr.html?mdOrder=Yco1duIqHQxaU4AAF4OR"
        }
    }
}

4. Handling Payment Results

After a transaction is completed, your app will receive the order_number as a query parameter in the deep link. You can fetch the transaction details using fetchTransaction:

import 'package:flutter_epay/flutter_epay.dart';
import 'package:flutter/material.dart';
 
class PaymentResultScreen extends StatefulWidget {
  final String orderNumber;
  const PaymentResultScreen({required this.orderNumber});
 
  @override
  _PaymentResultScreenState createState() => _PaymentResultScreenState();
}
 
class _PaymentResultScreenState extends State<PaymentResultScreen> {
  final epay = FlutterEpay();
  Map<String, dynamic>? transaction;
  bool loading = true;
 
  @override
  void initState() {
    super.initState();
    fetchTransactionDetails();
  }
 
  void fetchTransactionDetails() async {
    try {
      final data = await epay.fetchTransaction(widget.orderNumber);
      setState(() {
        transaction = data['data']['attributes'];
        loading = false;
      });
    } catch (error) {
      print("Error fetching transaction: \$error");
      setState(() => loading = false);
    }
  }
 
  @override
  Widget build(BuildContext context) {
    if (loading) return CircularProgressIndicator();
    return Column(
      children: [
        Text("Transaction Status: \${transaction?['status']}", style: TextStyle(fontSize: 18)),
        Text("Amount: \${transaction?['amount']}", style: TextStyle(fontSize: 18)),
      ],
    );
  }
}

Transaction Object Structure:

class TransactionAttributes {
  final String actionCode;
  final String actionCodeDescription;
  final String amount;
  final String confirmationStatus;
  final String orderNumber;
  final String status;
 
  TransactionAttributes({
    required this.actionCode,
    required this.actionCodeDescription,
    required this.amount,
    required this.confirmationStatus,
    required this.orderNumber,
    required this.status,
  });
}

5. Testing the Payment Flow

Before going live, test your integration using Guiddini’s sandbox environment. Use test API keys to simulate transactions.

6. Error Handling

try {
  final response = await epay.initiatePayment(amount: 100);
  if (response == null || response['data']['attributes']['status'] != 'processing') {
    throw Exception("Payment failed");
  }
} catch (error) {
  print("Payment Failed: \$error");
}

Conclusion

With these steps, you can efficiently integrate and manage payments using flutter_epay in your Flutter app.

On this page