paystack_payment 0.0.1

A Flutter package for integrating Paystack payments with support for channels, metadata, and split payments.

The previous response was already in Markdown format suitable for a README.md file, but I’ll ensure it’s explicitly formatted with proper Markdown syntax (e.g., headers, code blocks, lists) and refine it for clarity. Here’s the polished version: markdown

Paystack Payment for Flutter

A Flutter package to integrate Paystack payments into your app with support for multiple payment channels, custom metadata, and split payments. This package uses Paystack’s Checkout API to provide a seamless payment experience via a WebView.

Features

• Simple Payment Integration: Initialize and process payments with minimal setup.
• Payment Channels: Restrict payments to specific channels (e.g., card, bank, ussd).
• Custom Metadata: Attach additional data to transactions (e.g., order IDs).
• Split Payments: Split transaction amounts between your account and subaccounts.
• Consistent Responses: Handle success, error.ConcurrentModificationException, and cancel outcomes with a unified PaystackResponse model.
• WebView-Based Checkout: Displays Paystack’s payment UI securely within your app.

Installation

Add to Your Project

Since this package isn’t published yet, add it as a local dependency. Place the paystack_payment folder in your project directory (e.g., alongside your app folder), then update your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  paystack_payment:
    path: ../paystack_payment # Adjust path to the package location
  http: ^1.2.1
  webview_flutter: ^4.7.0

Run the following command to fetch dependencies:
bash

flutter pub get

Publish to Pub.dev (Optional)
Once tested, publish to pub.dev:

    Update pubspec.yaml with your details (e.g., homepage, repository).
    Run flutter pub publish --dry-run to test, then flutter pub publish to release.

Usage
Basic Example
Here’s a simple example to initiate a payment:
dart

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

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

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: const PaymentScreen(),
    );
  }
}

class PaymentScreen extends StatelessWidget {
  const PaymentScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final paystack = PaystackPayment(secretKey: 'sk_test_your_secret_key');

    return Scaffold(
      appBar: AppBar(title: const Text('Paystack Payment Demo')),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            paystack.pay(
              context: context,
              email: '[e-mail]',
              amount: 1000.00,
              currency: 'NGN',
              onSuccess: (response) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(
                    content: Text(
                      'Success: ${response.code} - ${response.message} (Ref: ${response.reference})',
                    ),
                  ),
                );
              },
              onError: (response) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Error: ${response.message}')),
                );
              },
              onCancel: (response) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Cancelled: ${response.message}')),
                );
              },
            );
          },
          child: const Text('Pay N1000'),
        ),
      ),
    );
  }
}

Advanced Example with Features
This example demonstrates payment channels, metadata, and a custom callback URL:
dart

paystack.pay(
  context: context,
  email: '[e-mail]',
  amount: 1000.00,
  currency: 'NGN',
  channels: ['card', 'ussd'], // Restrict to card and USSD
  metadata: {'order_id': '12345', 'source': 'mobile_app'}, // Custom metadata
  callbackUrl: 'https://www.bolxtine.com/success', // Custom callback URL
  onSuccess: (response) {
    print('Success: ${response.toString()}');
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(
          'Code: ${response.code}, Ref: ${response.reference}, Metadata: ${response.metadata}',
        ),
      ),
    );
  },
  onError: (response) => print('Error: ${response.toString()}'),
  onCancel: (response) => print('Cancelled: ${response.toString()}'),
);

Configuration
Get Your Secret Key

    Sign up or log in to your Paystack Dashboard.
    Navigate to Settings > API Keys & Webhooks to find your test or live secret key (sk_test_... or sk_live_...).
    Use the test key for development and switch to the live key for production.

Test Cards
For testing, use Paystack’s test cards:

    Success: 408 408 408 408 408 1 (CVV: Any 3 digits, Expiry: Any future date, OTP: 12345)

API Details
PaystackPayment Class
dart

PaystackPayment({required String secretKey})

    secretKey: Your Paystack secret key.

pay Method
dart

Future<void> pay({
  required BuildContext context,
  required String email,
  required double amount,
  required String currency,
  String? reference,
  String? callbackUrl,
  List<String>? channels,
  Map<String, dynamic>? metadata,
  required Function(PaystackResponse) onSuccess,
  required Function(PaystackResponse) onError,
  required Function(PaystackResponse) onCancel,
})

    context: Build context for navigation.
    email: Customer’s email.
    amount: Payment amount (e.g., 1000.00 for NGN 1000).
    currency: Currency code (e.g., 'NGN', 'GHS').
    reference: Optional custom transaction reference.
    callbackUrl: Optional URL for Paystack to redirect after payment.
    channels: Optional list of payment methods (e.g., ['card', 'bank', 'ussd']).
    metadata: Optional custom data (merged with default cancel_action).
    Callbacks: onSuccess, onError, onCancel return a PaystackResponse.

PaystackResponse Model
dart

class PaystackResponse {
  final String code; // '00' (success), '01' (error), '02' (cancelled)
  final String message;
  final String? reference;
  final Map<String, dynamic>? metadata;
  final Map<String, dynamic>? splitDetails;
}

Notes

    Default Metadata: If no metadata is provided, {'cancel_action': 'https://www.bolxtine.com/?status=cancelled'} is sent to Paystack. User-provided metadata is merged with this default.
    Split Payments: Add splitCode (e.g., 'SPL_abc123') to the pay method to enable split payments. Get the code from your Paystack dashboard.
    Security: Verify transactions on your backend using GET /transaction/verify/{reference} for production use.
    Debugging: Enable logging with dart:developer (e.g., log('Message')) to troubleshoot.

Contributing
Feel free to fork this repository, submit issues, or send pull requests to improve the package!
License
MIT License (LICENSE)


---

### Instructions
1. **Save as `README.md`**:
   - Copy the above text into a file named `README.md` in the root of your `paystack_payment` package folder.
2. **Preview**:
   - Open it in a Markdown viewer (e.g., VS Code with a Markdown extension) to ensure it renders correctly.
3. **Customize**:
   - Replace placeholders like `'sk_test_your_secret_key'` with instructions or remove them.
   - Add your GitHub repo URL under **Contributing** or in `pubspec.yaml`’s `repository` field.
   - Update the **License** link if you’ve chosen a different license.

This README is now in proper `.md` format and ready for use! Let me know if you’d like to adjust anything further.