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.

Libraries

waffy_sdk_flutter