waffy_sdk_flutter 0.1.0

Official Waffy payments SDK for Flutter. Embed the Waffy checkout in your app and get success or failure callbacks.

waffy_sdk_flutter

waffy_sdk_flutter is a small Flutter SDK that embeds the Waffy checkout flow in a WebView. You pass in a Waffy payment URL and a user token, and the SDK:

• Appends the user token to the URL as a query parameter.
• Loads the checkout in a WebView.
• Listens for redirects that indicate payment success or failure.
• Exposes simple callbacks so your app can react to the result.

---

Features

• ✅ Simple WaffyPaymentWebView widget to start a payment flow.
• ✅ Automatically injects userTokenUrl into the payment URL.
• ✅ Notifies you when:
  • The payment succeeds or fails.
  • The payment flow completes with a status and optional message.
  • The underlying WebView URL changes.
• ✅ Uses webview_flutter under the hood.

---

Getting started

1. Add dependency

flutter pub add waffy_sdk_flutter

Or add it manually to your app's pubspec.yaml:

dependencies:
  waffy_sdk_flutter: ^0.1.0

2. Platform setup

This package uses webview_flutter.

Follow the platform-specific setup in its documentation if you have not already configured WebView for your Flutter app (e.g. iOS minimum version, Android WebView requirements).

---

Usage

Basic example

The main entry point is the WaffyPaymentWebView widget.

• paymentUrl: The Waffy checkout URL you receive from your backend.
• userToken: The token that identifies the current user in your system.
• onPaymentComplete: Called once when the flow finishes (success or failure).
• onPaymentSuccess: Convenience callback when the result is successful.
• onPaymentFailure: Convenience callback when the result is failed, with a message.
• onUrlChange: Called for every URL change inside the WebView.

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

class WaffyCheckoutPage extends StatelessWidget {
  const WaffyCheckoutPage({
    super.key,
    required this.paymentUrl,
    required this.userToken,
  });

  final String paymentUrl;
  final String userToken;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Waffy Checkout'),
      ),
      body: WaffyPaymentWebView(
        paymentUrl: paymentUrl,
        userToken: userToken,
        onPaymentComplete: (status, message) {
          switch (status) {
            case WaffyPaymentStatus.success:
              // Handle success (e.g. navigate, show success UI).
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Payment success: $message')),
              );
              break;
            case WaffyPaymentStatus.failed:
              // Handle failure (e.g. show error, allow retry).
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Payment failed: $message')),
              );
              break;
          }
        },
        onUrlChange: (url) {
          // Optional: inspect URL changes for analytics or debugging.
          debugPrint('Waffy WebView URL changed: $url');
        },
      ),
    );
  }
}

---

How the payment result is detected

Internally, WaffyPaymentWebView:

1. Takes your paymentUrl and appends a userTokenUrl query parameter with the provided userToken.
2. Loads that URL in a WebView.
3. Listens to URL changes:
   • If the URL contains status=SUCCESS, it:
     • Calls onPaymentComplete(WaffyPaymentStatus.success, message).
     • Calls onPaymentSuccess() if provided.
   • If the URL contains status=FAILED, it:
     • Calls onPaymentComplete(WaffyPaymentStatus.failed, message).
     • Calls onPaymentFailure(message) if provided.
   • message is taken from the message query parameter of the URL, if present.

Your backend / Waffy checkout implementation is responsible for redirecting to a URL with status=SUCCESS or status=FAILED (and optional message).

---

API reference

WaffyPaymentWebView

Constructor parameters:

• paymentUrl (required): Base payment/checkout URL from your backend/Waffy.
• userToken (required): Token for the current user; added as userTokenUrl query parameter.
• onPaymentSuccess: void Function()? – called when the payment succeeds.
• onPaymentFailure: void Function(String message)? – called when the payment fails.
• onPaymentComplete: void Function(WaffyPaymentStatus status, String message)? – called once when the payment flow completes.
• onUrlChange: void Function(String? url)? – called on any URL change inside the WebView.
• webViewController: Optional WebViewController if you want to provide your own.

WaffyPaymentStatus

enum WaffyPaymentStatus {
  success,
  failed,
}

---

Support

For integration help or to report an issue, contact the Waffy team via waffyapp.com.