CoFee Payment Flutter SDK

This SDK provides a simple way to integrate CoFee Payment into your Flutter applications. It handles the payment flow, including opening the payment page and monitoring for completion. It then calls a callback, and you are responsible for checking the payment status after the callback.

Features

• Easy Integration: Quickly integrate CoFee Payment with minimal code.
• Environment Support: Supports both sandbox (testing) and production environments.
• Robust Error Handling: Comprehensive error handling with detailed error types and messages.
• Completion Callback: Notifies your application when the payment process has potentially finished. You must check the payment status after receiving this callback.

Installation

Add the following to your pubspec.yaml file:

dependencies:
  cofee_payment_flutter: ^1.0.2

This package requires Dart SDK ^3.6.0 and Flutter ">=3.3.0".

Then run:

flutter pub get

Usage

Basic Usage

import 'package:cofee_payment_flutter/cofee_payment_flutter.dart';

// Initialize the SDK with your client ID
final coFeePayment = CoFeePayment(
  clientId: 'your-client-id',
  paymentEnvironment: PaymentEnvironment.sandbox, // or PaymentEnvironment.production
);

// Initiate a payment
coFeePayment.pay(
  'order-123', // Order ID
  onFinish: () {
    // Handle payment completion
    print('Payment completed');
  },
  onError: (error) {
    // Handle payment errors
    print('Payment failed: ${error.message}');
  },
);

Complete Example

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

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  final CoFeePayment _cofeePayment = CoFeePayment(
    clientId: "YOUR_CLIENT_ID",
    paymentEnvironment: PaymentEnvironment.sandbox,
  );

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('CoFee Payment Example'),
        ),
        body: Center(
          child: ElevatedButton(
            onPressed: () {
              _initiatePayment();
            },
            child: const Text('Pay with CoFee'),
          ),
        ),
      ),
    );
  }

  void _handlePaymentCompletion() {
    // Payment is complete! Handle success here.
    print("Payment completed!");
  }

  void _handlePaymentError(PaymentException error) {
    // Handle different error types appropriately
    switch (error.errorType) {
      case PaymentErrorType.invalidOrderId:
        print("Invalid order ID: ${error.message}");
        break;
      case PaymentErrorType.network:
        print("Network error: ${error.message}");
        break;
      case PaymentErrorType.api:
        print("API error: ${error.message}");
        break;
      default:
        print("Payment error: ${error.message}");
    }
  }

  void _initiatePayment() {
    _cofeePayment.pay(
      "order_12345",  // Example order ID
      onFinish: _handlePaymentCompletion,
      onError: _handlePaymentError,
    );
  }
}

## API Reference

### CoFeePayment

The main class for interacting with the CoFee payment system.

#### Constructor

```dart
CoFeePayment({
  required String clientId,
  required PaymentEnvironment paymentEnvironment,
})

• clientId: Your CoFee client ID for authentication.
• paymentEnvironment: The environment to use (sandbox or production).

Methods

pay

Future<void> pay(
  String orderId, {
  required PaymentCompletionCallback onFinish,
  required PaymentErrorCallback onError,
})

Initiates the payment flow for the specified order ID.

• orderId: The unique identifier for the payment order.
• onFinish: A callback function that is called when the payment is complete.
• onError: A callback function that is called when an error occurs.

Callback Types

PaymentCompletionCallback

typedef PaymentCompletionCallback = void Function();

A callback function type that is called when the payment is complete.

PaymentErrorCallback

typedef PaymentErrorCallback = void Function(PaymentException error);

A callback function that receives payment errors.

Error Handling

The SDK provides several error types through the PaymentErrorType enum:

• invalidOrderId: When the provided order ID is invalid or not found
• network: For network connectivity issues
• api: For API-related errors
• invalidResponse: When the API response format is invalid
• unknown: For unexpected errors

Each error includes:

• A descriptive message
• HTTP status code (when applicable)
• Error code from the API (when available)
• Original error cause (for debugging)

Testing

To run the tests:

flutter test

Troubleshooting

Common Issues

1. Payment fails to initialize

   • Check that your client ID is correct
   • Ensure you have an active internet connection
   • Verify that the order ID is valid
   • Confirm you're using the correct environment (sandbox/production)

2. In-app browser doesn't open

   • Make sure you have the latest version of the SDK
   • Check that you have the necessary permissions
   • Verify that your device supports in-app browsers

3. Network Errors

   • Check your internet connection
   • Verify your firewall settings
   • Ensure the API endpoints are accessible

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0