Flutter SDK

Flutter SDK

Embed the Waffy checkout in your Flutter app with a single widget and get notified when the payment succeeds or fails.

View on pub.dev

Installation:

flutter pub add waffy_sdk_flutter

Installation

Get started with the Flutter SDK in minutes

Install SDK

Add the package from pub.dev

flutter pub add waffy_sdk_flutter

# or in pubspec.yaml
dependencies:
  waffy_sdk_flutter: ^0.6.0

Platform Setup

The SDK uses webview_flutter under the hood

No extra install is needed — webview_flutter is pulled in automatically. Make sure your app meets its Android and iOS requirements:

webview_flutter platform requirements

Requires Dart 3.5+ and Flutter 3.24+.

Usage

Integrate Waffy payments into your Flutter app

Basic Payment Integration

A checkout screen that reacts to the payment result

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

class PaymentScreen extends StatelessWidget {
  const PaymentScreen({
    super.key,
    required this.paymentUrl, // from your backend
    required this.ticket, // requested by your backend right before opening checkout
  });

  final String paymentUrl;
  final String ticket;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Waffy Checkout')),
      body: WaffyPaymentWebView.ticket(
        paymentUrl: paymentUrl,
        ticket: ticket,
        onPaymentComplete: (status, message) {
          switch (status) {
            case WaffyPaymentStatus.success:
              Navigator.of(context).pop(true);
            case WaffyPaymentStatus.failed:
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Payment failed: $message')),
              );
          }
        },
        onUrlChange: (url) => debugPrint('Waffy URL: $url'),
      ),
    );
  }
}

Authentication

Pass exactly one of ticket, hint or userToken

Authentication options

The SDK appends the value you pass to the payment URL

ParameterAppended asWhen to use
ticketticketRecommended for new integrations. A one-time payment ticket from the payment ticket request. It expires after 5 minutes, so request it right before opening checkout.
hintlogin_hintA login hint that identifies the customer (their phone number).
userTokenuserTokenUrlLegacy customer token. Existing integrations keep working unchanged; new integrations should use ticket.

Use the named constructor for your option: WaffyPaymentWebView.ticket, WaffyPaymentWebView.hint or WaffyPaymentWebView.userToken. Each accepts only its own value, so passing more than one is a compile-time error.

The default WaffyPaymentWebView(...) constructor still accepts all three for existing integrations. Passing none, or more than one, fails an assert in debug mode and throws a WaffyAuthError when the widget is built. Empty strings count as not provided.

ticket, hint and the named constructors require waffy_sdk_flutter 0.6.0 or later.

// Payment ticket (recommended)
WaffyPaymentWebView.ticket(paymentUrl: paymentUrl, ticket: ticket)

// Login hint: the customer's phone number, e.g. '+9665XXXXXXXX'
WaffyPaymentWebView.hint(paymentUrl: paymentUrl, hint: customerPhone)

// Legacy user token
WaffyPaymentWebView.userToken(paymentUrl: paymentUrl, userToken: userToken)

How the payment result is detected

  1. The SDK appends your authentication value (ticket, login_hint or userTokenUrl) to paymentUrl and loads it in a WebView.
  2. When the checkout redirects to a URL containing status=SUCCESS or status=FAILED, it calls onPaymentComplete once, then onPaymentSuccess or onPaymentFailure.
  3. The optional message query parameter is passed to your callbacks.

Always confirm the final payment status on your backend (via the Payments API or webhooks) before fulfilling an order. The in-app callback is for UX only.

Parameters

Complete reference for the WaffyPaymentWebView widget

*
paymentUrl (required)

The Waffy payment page URL to load in the WebView.

Type: String

Create the payment from your backend and pass the returned URL. Example: https://app.waffyapp.com/external/contract-id?client_id=123

*
ticket | hint | userToken (required)

Authenticates the customer on the payment page. Pass exactly one.

Type: String?

ticket is appended as ticket (recommended),hint as login_hint, anduserToken as userTokenUrl (legacy). SeeAuthentication above.

onPaymentComplete (optional)

Called once when the payment flow finishes.

Type: void Function(WaffyPaymentStatus status, String message)?

status is WaffyPaymentStatus.success or WaffyPaymentStatus.failed. message comes from the redirect URL's message parameter, or is an empty string.

onPaymentSuccess (optional)

Convenience callback called when the payment succeeds.

Type: VoidCallback?

Called right after onPaymentComplete.

onPaymentFailure (optional)

Convenience callback called when the payment fails.

Type: void Function(String message)?

Receives the same message as onPaymentComplete.

onUrlChange (optional)

Called whenever the WebView navigates to a new URL.

Type: void Function(String? url)?

Useful for analytics or debugging the payment flow. url may be null when the WebView is cleared.

webViewController (optional)

Optional controller from webview_flutter to use instead of a new one.

Type: WebViewController?

Pass your own controller if you need direct access to the WebView (for example to reload it).

WaffyPaymentStatus

The result passed to onPaymentComplete

enum WaffyPaymentStatus {
  success,
  failed,
}

Key Features

Everything you need for mobile payment integration

One Widget

Drop WaffyPaymentWebView into any screen

Event Callbacks

Payment result and URL change callbacks

Android & iOS

Built on the official webview_flutter plugin

Ready to Get Started?

Start integrating Waffy payments into your Flutter app in minutes

Need Help?

Check out our examples and documentation