Paymob Native SDK #

A Flutter plugin that integrates the Paymob payment gateway into your Android and iOS applications. It wraps the native Paymob SDK and exposes a simple Dart API to launch the payment UI and receive the transaction result.

Table of Contents #

• Features
• Installation
• Prerequisites
• Android Setup
• Usage
  • 1. Create a Payment Intention (Backend)
  • 2. Start Payment (Flutter)
  • 3. Handle the Result
• API Reference
  • PaymobSdk
  • PaymobParams
  • PaymobCheckoutStatus
• Complete Example
• Security Notes
• Troubleshooting

Features #

• Launch the Paymob native payment UI with a single method call.
• Customize the payment button appearance (background color, text color).
• Control the "Save Card" feature (show/hide, default state).
• Receive a typed transaction status upon completion.
• Supports Android and iOS.

Installation #

Add the package to your pubspec.yaml:

dependencies:
  paymob_sdk: <latest>

Then run:

flutter pub get

Android Setup #

1. Add JitPack Repository #

In your android/settings.gradle.kts, add JitPack inside the pluginManagement repositories block:

pluginManagement {
    repositories {
        // ... your existing repositories
        maven { url = uri("https://jitpack.io") }
    }
}

2. Enable Data Binding #

In your app's android/app/build.gradle.kts, enable Data Binding inside the android block:

android {
    // ... your existing config

    buildFeatures {
        dataBinding = true
    }
}

⚠️ Without this, the app will crash on Android.

Prerequisites #

Before using this plugin you need:

1. A Paymob merchant account — sign up at Paymob Dashboard.
2. Your Public Key (publicKey) — found in your Paymob dashboard.
3. A Secret Key (secretKey) — keep this on your backend only, never ship it inside the app.
4. A Payment Intention created on your backend for each transaction, which returns a client_secret.

Usage #

1. Create a Payment Intention (Backend) #

Before launching the payment UI, your backend server must create a Payment Intention via the Paymob API and return the client_secret to your app.

📖 Follow the official Paymob documentation to implement this on your backend: Create a Payment Intention — Paymob Docs

Once your backend creates the intention, return only the client_secret to your Flutter app and pass it to PaymobParams.

⚠️ Never create the Payment Intention from inside the Flutter app. Your Secret Key must remain exclusively on your backend server.

2. Start Payment (Flutter) #

import 'package:paymob_sdk/paymob_sdk.dart';

final _paymobSdk = PaymobSdk();

Future<void> pay() async {
  // Obtain client_secret from YOUR backend
  final clientSecret = await yourBackend.createPaymentIntention(amount: 100);

  await _paymobSdk.startPayment(
    PaymobParams(
      publicKey: 'YOUR_PUBLIC_KEY',
      clientSecret: clientSecret,
      appName: 'My App',                          // optional
      buttonBackgroundColor: Colors.blue,         // optional
      buttonTextColor: Colors.white,              // optional
      saveCardDefault: false,                     // optional
      showSaveCard: true,                         // optional
    ),
    onCheckoutStatus: (status) {
      // handle status
    },
  );
}

3. Handle the Result #

startPayment accepts an optional onCheckoutStatus callback that is invoked with the final PaymobCheckoutStatus when the flow completes:

await _paymobSdk.startPayment(
  params,
  onCheckoutStatus: (status) {
    switch (status) {
      case PaymobCheckoutStatus.successful:
        // Payment was completed successfully
        break;
      case PaymobCheckoutStatus.rejected:
        // Payment was declined / rejected
        break;
      case PaymobCheckoutStatus.pending:
        // Payment is pending (e.g. cash payment awaiting confirmation)
        break;
      case PaymobCheckoutStatus.unknown:
        // Unexpected state
        break;
    }
  },
);

API Reference #

PaymobSdk #

The main entry point of the plugin.

class PaymobSdk {
  Future<PaymobCheckoutStatus?> startPayment(
    PaymobParams params, {
    void Function(PaymobCheckoutStatus status)? onCheckoutStatus,
  });
}

PaymobParams #

Configuration object passed to startPayment.

const PaymobParams({
  required String publicKey,
  required String clientSecret,
  String? appName,
  Color? buttonBackgroundColor,
  Color? buttonTextColor,
  bool? saveCardDefault,
  bool? showSaveCard,
});

PaymobCheckoutStatus #

An enum representing the final state of a payment attempt.

enum PaymobCheckoutStatus {
  successful,  // Transaction completed and approved
  rejected,    // Transaction was declined
  pending,     // Transaction is awaiting offline confirmation
  unknown,     // Unrecognised status returned by the SDK
}

Complete Example #

import 'package:flutter/material.dart';
import 'package:paymob_sdk/paymob_sdk.dart';

class CheckoutPage extends StatelessWidget {
  CheckoutPage({super.key});

  final _paymobSdk = PaymobSdk();
  static const _publicKey = 'YOUR_PUBLIC_KEY';

  Future<void> _pay(BuildContext context) async {
    // Step 1: Get client_secret from your backend
    final clientSecret = await yourBackendService.createIntention(amount: 100);

    // Step 2: Launch the payment UI
    await _paymobSdk.startPayment(
      PaymobParams(
        publicKey: _publicKey,
        clientSecret: clientSecret,
        appName: 'My Store',
        buttonBackgroundColor: Colors.indigo,
        buttonTextColor: Colors.white,
        showSaveCard: true,
        saveCardDefault: false,
      ),
      // Step 3: React to the result
      onCheckoutStatus: (status) {
        if (!context.mounted) return;
        switch (status) {
          case PaymobCheckoutStatus.successful:
            ScaffoldMessenger.of(context).showSnackBar(
              const SnackBar(content: Text('Payment successful!')),
            );
            break;
          case PaymobCheckoutStatus.rejected:
            ScaffoldMessenger.of(context).showSnackBar(
              const SnackBar(content: Text('Payment rejected. Please try again.')),
            );
            break;
          case PaymobCheckoutStatus.pending:
            ScaffoldMessenger.of(context).showSnackBar(
              const SnackBar(content: Text('Payment pending. You will be notified.')),
            );
            break;
          default:
            ScaffoldMessenger.of(context).showSnackBar(
              const SnackBar(content: Text('Payment status unknown.')),
            );
        }
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Checkout')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => _pay(context),
          child: const Text('Pay Now'),
        ),
      ),
    );
  }
}

Security Notes #

Troubleshooting #

App crashes immediately when calling startPayment on Android

• This is most likely caused by missing Data Binding configuration. Make sure you have added the following to your android/app/build.gradle.kts:

  android {
      buildFeatures {
          dataBinding = true
      }
  }
  

  Then run flutter clean && flutter pub get and rebuild the app.

PlatformException is thrown when calling startPayment

• Make sure the publicKey and clientSecret are correct and not expired.
• Ensure the native Paymob SDK is properly linked (run pod install for iOS, sync Gradle for Android).

Payment UI does not appear on iOS

• Run pod install inside the ios/ folder of your project.
• Confirm that PaymobSdkPlugin is listed in GeneratedPluginRegistrant.

unknown status returned unexpectedly

• This may happen if the user force-closes the payment sheet. Handle it gracefully, e.g. by prompting the user to retry.