Flutter

The Flutter SDK lets you take Mobile Money, card and wallet payments in your app, with a ready-made payment sheet.

Install

flutter pub add wajub_mobile

Or pin it in pubspec.yaml with wajub_mobile: ^1.6.0.

The package's other dependencies need no code of yours.

dependency_overrides:
  flutter_stripe: 11.4.0
  stripe_android: 11.4.0
  stripe_ios: 11.4.0
  stripe_platform_interface: 11.4.0

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity()

Quick start

Three steps, and only the middle one runs in the app.

1. Your server creates the payment. POST /payments with your secret key, then hand the app the authorization_token of the answer. The package never holds a secret key. Create a payment

final response = await http.post(
  Uri.parse('https://api.yourshop.com/checkout'),
  headers: {'Content-Type': 'application/json'},
  body: jsonEncode({'cart_id': cart.id}),
);

final authorizationToken = jsonDecode(response.body)['authorization_token'] as String;

2. The app presents the sheet with that token and reads the result.

import 'package:wajub_mobile/wajub_mobile.dart';

Future<void> pay(BuildContext context, String authorizationToken) async {
  final result = await presentWajubCheckout(
    context,
    PresentOptions(sessionToken: authorizationToken),
  );

  switch (result) {
    case CheckoutComplete(:final payment):
      // Paid: payment.id is Wajub's payment id. Confirm it on your server first.
      showReceipt(payment.id);
    case CheckoutProcessing():
      // Closed while a payment was running: money may still move.
      showPending();
    case CheckoutFailed(:final error):
      // A failure, an ended or expired payment, or a load error.
      showError(error.message);
    case CheckoutCancelled(:final reason):
      // "Cancel payment", or closed before any payment.
      debugPrint('cancelled: ${reason.wireName}');
  }
}

3. Your server confirms. The result is what the payer saw, not proof of payment. Deliver on the payment.succeeded webhook, or after GET /payments/{id} with payment.id.

presentWajubCheckout resolves exactly once, when the sheet closes, and Wajub.present(context, options) is the same call. CheckoutResult is a sealed class, so the switch above is exhaustive. Presenting a second sheet while one is open throws a WajubError whose code is sheet_already_presented, and leaves the open sheet alone. A new sheet can open as soon as the last one has closed, from its onComplete too.

Options

PresentOptions(
  sessionToken: authorizationToken,
  locale: 'fr',
  appearance: const Appearance(theme: 'night'),
  loader: WajubLoader.skeleton,
  readyTimeout: const Duration(seconds: 15),
  returnUrl: 'https://shop.example.com/app/return',
  mobileMoney: const MobileMoneyOptions(
    country: 'CI',
    countryLocked: true,
    operatorMode: OperatorMode.detect,
  ),
  cancelOnDismiss: true,
  autoCloseSuccess: const Duration(seconds: 3),
  stripe: const StripeOptions(appPublishableKey: 'pk_live_…'), // your app's own Stripe key, if it has one
  callbacks: CheckoutCallbacks(onStateChange: (event) => debugPrint(event.state.wireName)),
)

Callbacks and states

Every callback is optional and runs on the UI thread, in this order for one payment: onReady, then onStateChange on each change, onPaymentStarted and onRedirect, then onSuccess, onError or onCancel, and onComplete exactly once. A callback that throws does not break the sheet.

CheckoutCallbacks(
  onReady: (ReadyEvent e) {},              // sessionId, environment, amount, currency, methods
  onStateChange: (StateChangeEvent e) {},  // state (CheckoutState), method
  onLoadError: (WajubError error) {},      // the sheet could not offer a payment
  onPaymentStarted: (PaymentStartedEvent e) {}, // method, channel
  onRedirect: (RedirectEvent e) {},        // e.url, right before the system browser opens
  onSuccess: (PaymentSuccess payment) {},
  onError: (WajubError error) {},          // every failure the payer sees, retryable ones included
  onCancel: (CancelEvent e) {},            // reason (CancelReason), redirectUrl
  onComplete: (CheckoutResult result) {},  // what presentWajubCheckout resolves with
)

state.wireName is the state's name: INITIATED, COLLECTING_DETAILS, PROCESSING, APPROVAL_REQUIRED, USSD_REQUIRED, PAYER_OTP_REQUIRED, OTP_REQUIRED, PIN_REQUIRED, PHONE_REQUIRED, BIRTHDAY_REQUIRED, ADDRESS_REQUIRED, 3DS_REQUIRED, VERIFYING, PENDING, SUCCESS, FAILED, EXPIRED, CANCELLED. The Dart cases are in camel case: CheckoutState.collectingDetails, CheckoutState.payerOtpRequired, CheckoutState.threeDsRequired. What the payer sees in each one is on Mobile SDKs.

Results

Every result also has status: complete, processing, failed or cancelled. CancelReason is payerCancelled, dismissed or hostGone, and reason.wireName gives payer_cancelled, dismissed or host_gone.

PaymentSuccess carries id (Wajub's payment id, what GET /payments/{id} takes), reference (yours), amount (what the payer paid, fee included, in major units), currency, method, status (always success), timestamp (ISO 8601) and receiptUrl.

The sheet never shows a failure when the outcome is unknown: it shows "Payment in progress" and keeps waiting, and closing it then resolves processing. When the page that presented the sheet goes away, the sheet resolves cancelled with hostGone before any payment, processing once one has started, complete after a success, and never cancels the payment. If the app's process dies, read the outcome on your server, or with WajubSession.status(), at the next launch.

Cancelling and closing

The payer closes the sheet with its close button, a swipe down, the back button or a tap outside it.

"Cancel payment" in the sheet cancels the payment for good and resolves CheckoutCancelled with payerCancelled. It is not offered while a payment is under way. See Mobile SDKs.

Appearance

The appearance option sets the sheet's look. The keys, presets and variables are on Appearance.

const appearance = Appearance(
  theme: 'stripe',            // presets: stripe, night, flat, none; or light, dark, auto
  colorScheme: 'auto',        // light, dark or auto, which follows the phone
  inherit: true,              // read Theme.of(context) where you set nothing
  variables: AppearanceVariables(
    colorPrimary: '#0F766E',
    colorBackground: '#FFFFFF',
    colorText: '#171717',
    colorDanger: '#B91C1C',
    fontFamily: 'Inter',      // used when your app ships it
    borderRadius: '12px',
    spacingUnit: '4px',
  ),
  buttonTextColor: '#FFFFFF',
  disableAnimations: false,
);

// Or from a map, such as decoded JSON:
final shared = Appearance.fromMap(jsonDecode(appearanceJson) as Map<String, Object?>);

What you leave unset comes from the merchant's branding in the Dashboard, then Wajub's default light or dark palette. See Mobile SDKs.

Mobile Money

One form covers every Mobile Money operator of the payment: the country, the operators, and the number with the country's dial code, formatted as it is typed. The number preselects its operator until the payer picks one by hand. After Pay, the sheet shows "Approve the payment on your phone", or a USSD code to dial.

See Mobile SDKs.

Cards

Stripe's card form needs FlutterFragmentActivity on Android, see Install. If your app also takes its own Stripe payments with flutter_stripe, pass your app's key in stripe: StripeOptions(appPublishableKey: …) so your own Stripe payments keep working.

Other cards open a secure page of the payment provider in the system browser, and in sandbox the sheet shows a test card form. See Mobile SDKs.

Confirmation steps

When a payment needs one more check, the sheet shows it on its own screen: a one-time code, the card PIN, a phone number, a date of birth or a billing address. A wrong answer stays on the screen with the attempts left; an expired step or too many attempts end on the failure screen, with "Try again". See Mobile SDKs.

Errors

Every failure is a WajubError, an Exception. The sheet hands it to onLoadError or onError and puts it in CheckoutFailed.

Codes worth branching on: insufficient_funds, payment_declined, payment_attempt_ended (refused, nothing was charged), payment_failed, payment_cancelled, session_expired, shield_blocked, merchant_restricted, rate_limited, session_terminal_expired, unsupported_action, redirect_unavailable, and sheet_already_presented from presentWajubCheckout. The full list is on Mobile SDKs.

Your own UI

The sheet is the simplest integration. An app that draws its own payment screens uses the lower-level WajubSession, created with Wajub.createSession(authorizationToken) and described in the package's API reference on pub.dev.

Privacy

To make the payment, the SDK sends Wajub what the payer types. For fraud prevention, it also sends basic device information and a random install identifier, which is not the advertising identifier. What to declare in the App Store privacy labels and in Google Play's data safety form, category by category, is on Mobile SDKs.

Testing

Create the payment with a sandbox key: the whole flow runs in sandbox, sheet included, and the sheet shows a "Test mode" badge. Test numbers and cards are on Test scenarios.