fatoorah_pay 1.0.0

A comprehensive Flutter SDK for integrating MyFatoorah payment gateway with support for payments, subscriptions, transactions, and account management.

Fatoorah Pay SDK

Flutter Package to integrate with Fatoorah Pay

---

Getting Started

Welcome to Fatoorah Pay! This guide will help you integrate payment processing into your application in just a few steps.

Overview

Fatoorah Pay is a payment gateway service that enables you to:

• Accept card payments from customers
• Create shareable payment links
• Process payments programmatically
• Receive real-time webhook notifications
• Query transaction history

Quick Start

To know exactly how to start your integration with Fatoorah Pay before integrating this package to your app, please visit this README documentation:

Getting Started Guide

---

Features

• Type-Safe Models - Full IDE support with autocomplete
• Automatic Validation - Catch errors before API calls
• Payment Intents - Custom checkout with item tracking
• Payment Links - Simple redirect-based payments
• Transactions - Payment history and management
• Clean Error Handling - ApiResult<T> pattern
• Null-Safe - Fully null-safety compliant (Dart 3.9.2+)

---

Requirements

• Dart SDK: ^3.9.2 or higher
• Flutter: >=1.17.0
• Null Safety: Enabled (fully compliant)

---

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  fatoorah_pay: ^1.0.0

Then run:

flutter pub get

Payment Links

Simply create a link, share it with your customer, and they can pay directly.

What are Payment Links?

Payment links are pre-configured payment pages that you can share with customers via:

• Email
• SMS
• Social media
• Your website
• QR codes

Customers click the link, enter their payment details, and complete the payment - no coding required on your end.

When to Use Payment Links

Payment links are ideal for:

✅ Invoices - Send payment links with invoices ✅ One-time payments - Simple, quick payments ✅ Email/SMS campaigns - Share links in messages ✅ Manual order processing - Create links on-demand ✅ Non-integrated scenarios - When you can't integrate directly

Not ideal for:

❌ Real-time checkout flows (use Payment Intentions instead) ❌ Recurring subscriptions (use subscription endpoints) ❌ Complex multi-step processes

Create Payment Link

Creates a new payment link that can be shared with customers. Payment links allow customers to complete payments without requiring integration on your side.

Key Features:

• Shareable URL for customers
• Automatic expiration (default 24 hours)
• Webhook notifications on payment status changes
• Support for external references (invoice IDs, order IDs, etc.)

For complete code examples, see Payment Link Examples

List Payment Links

Retrieve a paginated list of all payment links for your account.

Supports filtering and sorting by various fields.

Note:

• Pagination starts from page 0 (not 1)
• page, size, sortBy, and sortDirection parameters are optional - if not provided, they won't be sent in the request

For complete code examples, see Payment Link Examples

Get Single Payment Link

Retrieve details of a specific payment link by its ID.

For complete code examples, see Payment Link Examples

---

Payment Intentions

Payment intentions represent the lifecycle of a payment from creation to completion. Use payment intentions when you want to integrate payments directly into your application flow with full programmatic control.

What are Payment Intentions?

Payment intentions are payment objects that you create programmatically and manage through their lifecycle. Unlike payment links (which are shareable URLs), payment intentions give you:

• Full control over the payment flow
• Detailed line items and billing information
• Programmatic status management
• Integration with your checkout process

When to Use Payment Intentions

Payment intentions are ideal for:

✅ E-commerce checkouts - Integrated checkout flows ✅ In-app payments - Mobile and web applications ✅ Custom checkout pages - Your own payment UI ✅ Multi-step processes - Complex payment flows ✅ Real-time status updates - Immediate payment confirmation

Not ideal for:

❌ Simple email/SMS payments (use Payment Links instead) ❌ Manual order processing (use Payment Links instead)

Key Features

• Programmatic payment processing
• Support for multiple line items
• Detailed billing information
• Webhook notifications
• Automatic expiration (default 24 hours)

Create Payment Intent

Creates a payment intention for processing a payment programmatically.

Payment intentions represent the lifecycle of a payment from creation to completion. Use this endpoint when you want to integrate payments directly into your application flow.

Key Features:

• Programmatic payment processing
• Support for multiple line items
• Detailed billing information
• Webhook notifications
• Automatic expiration (default 24 hours)

For complete code examples, see Payment Intent Examples

List Payment Intentions

Retrieve a paginated list of all payment intentions for your account.

Note:

• Pagination starts from page 0 (not 1)
• page, size, sortBy, and sortDirection parameters are optional - if not provided, they won't be sent in the request

For complete code examples, see Payment Intent Examples

Get Single Payment Intention

Retrieve details of a specific payment intention by its ID.

For complete code examples, see Payment Intent Examples

---

Transactions

List Transactions

Retrieve a paginated list of all transactions for your account with advanced filtering and search capabilities.

Note:

• Pagination starts from page 0 (not 1)
• page and size parameters are optional - if not provided, they won't be sent in the request
• Supports filtering by status, type, payment method, card type, date range, and text search across customer details

For complete code examples, see Transaction Examples

Get Single Transaction

Retrieve details of a specific transaction by its ID or display ID.

For complete code examples, see Transaction Examples

Refund Transaction

Initiates a refund for a previously successful transaction.

Key Features:

• Full or partial refunds supported
• Refund amount cannot exceed original transaction amount
• Creates a new refund transaction linked to the original
• Webhook notification sent when refund completes

For complete code examples, see Transaction Examples

Void Transaction

Voids a previously authorized but not captured transaction.

Key Features:

• Cancels authorization before capture
• No money is transferred
• Creates a new void transaction linked to the original
• Webhook notification sent when void completes

For complete code examples, see Transaction Examples

---

Documentation

• Examples Directory - Complete code examples for all features organized by section
• Dashboard: https://app.fatoorah.sa
• Documentation: https://fatoorah-pay.readme.io/
• Full Project Example: See the complete Flutter project example on GitHub for detailed implementation
• Issue Tracker: Report bugs, request features, or ask integration questions via the GitHub Issues page: https://github.com/fatoorahsa/fatoorah_pay_flutter_example/issues

---

Error Handling

The SDK uses an ApiResult<T> pattern for all operations:

result.when(
  onSuccess: (data) {
    // Handle success
  },
  onFailure: (error) {
    if (error is AuthenticationException) {
      // Invalid API key
    } else if (error is ValidationException) {
      // Validation failed
    } else if (error is NetworkException) {
      // Network issue
    } else if (error is ServerException) {
      // Server error (500, etc.)
    }
  },
);

---

Security

Never commit API keys!

final apiKey = Platform.environment['FATOORAH_API_KEY'] ?? '';

---

Support

Need help? We're here for you:

• Email: [e-mail]

---

License

MIT License - See LICENSE file

---

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.