Inttegro SDK for Flutter

The Inttegro SDK for Flutter presents Inttegro's native iOS and Android payment sheet through a typed Flutter plugin. The native SDKs own presentation, accessibility, authentication, payment collection, and lifecycle state.

Start with MCP

Before writing SDK code, connect your MCP client and ask MCP to design the integration for your mobile checkout flow. Use the resulting plan to define the boundary between your server, this SDK, and the Inttegro API.

Current payment methods

The published SDK currently supports mobile money. Card payments, Apple Pay, and Google Pay are not exposed in this version.

Requirements

Flutter 3.44 or later and Dart 3.12 or later
iOS 16 or later
Android API 26 or later
A merchant-backend endpoint that creates and finalizes an Inttegro order and returns its client-safe Order ID

Add the package from pub.dev, then rebuild the application so Flutter can register the native plugin:

flutter pub add inttegro_flutter

Hot reload cannot add a newly installed native plugin to a running application.

Payment lifecycle

Subscribe before presentingpaymentSheetEvents

Merchant backend
Create and finalize the order
Seal the cart, amount, currency, and payment settings before handing checkout to the app.
requires_payment
Return the Order ID
Mobile app
Initialize checkoutinitializePaymentSheet()
Provide the client-safe Order ID and configure the native payment sheet.
Mobile app
Present the payment sheetpresentPaymentSheet()
Open the native sheet. The SDK loads the checkout projection and renders payment collection.
Lifecycle hookPaymentSheetEventType.presented
Customer and Inttegro SDK
Run a payment attempt
Collect the payment method, confirmation, and authorization inside the sheet.
Lifecycle hookPaymentSheetEventType.paymentAttemptStarted
Payment attempt outcome?
Recoverable failurePaymentSheetEventType.paymentAttemptFailedThe sheet explains the failure and allows another attempt.↩ Retry step 4
Successful paymentPaymentSheetCompletedReturn a terminal result to the mobile app.Continue ↓
Confirmation and authorization
PaymentSheetEventType.paymentActionRequiredCheckout guides confirmation, authorization, or a redirect.
PaymentSheetEventType.paymentProcessingThe submitted payment remains pending.
↩ Re-evaluate the outcome
Mobile app
Handle the terminal resultPaymentSheetResult
Update the immediate UI for completion, cancellation, or an unrecoverable failure.
Verify authoritative state
Merchant backend
Verify before fulfillment
Confirm the owner-scoped Order state before releasing goods or services.
Order lookup or webhook

Your backend creates the order with its secret Inttegro API key, finalizes it to seal the amount and activate checkout, and returns only the resulting Order ID to the app. That handoff must finish before the app initializes or presents the payment sheet. “Finalized” means ready for payment—not paid or fulfilled.

final checkout = await merchantBackend.createCheckoutOrder(cart);
final orderId = checkout.orderId;

initializePaymentSheet validates and stores the configuration. The checkout network load begins after presentPaymentSheet opens the native sheet.

Start from a Buy link

Return a Buy link's public Purchase Intent ID to the app and initialize the same native sheet with purchaseIntentId instead of orderId:

await Inttegro.instance.initializePaymentSheet(
  PaymentSheetConfiguration(
    purchaseIntentId: buyLink.purchaseIntentId,
    returnUrl: Uri.parse('merchant-app://inttegro-return'),
  ),
);

The sheet gathers the Buy-link choices and payment details without creating an Order. When the payer presses Pay, Inttegro creates the finalized Order and starts the payment attempt together. Customer-selected pricing uses the currency, minimum, optional maximum, and suggested amounts returned by Checkout. Supply exactly one of orderId or purchaseIntentId; suggestions do not limit other valid values inside the range.

Native payment sheet

The Inttegro Flutter SDK presents a native payment sheet inside your app. Customers can choose a saved payment method or enter Mobile Money details, review the amount, and see when payment completes.

iOS
Android

5 steps

Light mode. Native Inttegro payment sheet presented over the Kora Market iOS demo, showing Mobile Money account entry for a payer without an attached payment method. — iOSLight
**Start the payment**Enter a Mobile Money account number when there is no attached payment method.

Light mode. Native Inttegro payment sheet on iOS with a complete Mobile Money account number, MTN selected, and the Pay action available. — iOSLight
**Review the account and provider**The suggested network remains selectable for ported numbers. A valid account makes Pay available.

Light mode. Native Inttegro payment sheet on iOS asking for the six-digit code sent by SMS to the customer’s masked Mobile Money number. — iOSLight
**Confirm with a code**Enter the one-time code sent to the masked recipient before continuing to provider approval.

Light mode. Native Inttegro payment sheet on iOS waiting for the customer to approve the payment in their Mobile Money prompt. — iOSLight
**Check your phone**Keep the sheet open while the customer approves the payment from their Mobile Money prompt.

Light mode. Native Inttegro payment sheet confirming a completed GHS 50 Mobile Money payment to Kora Market. — iOSLight
**Finish with confirmation**The terminal state confirms the paid amount and merchant before returning control to the host app.

React Native and Flutter use these same native payment sheets instead of reimplementing checkout. The Android robot is reproduced from work created and shared by Google and used according to the Creative Commons 3.0 Attribution License.

Present the payment sheet

import 'package:inttegro_flutter/events.dart';
import 'package:inttegro_flutter/payment_sheet.dart';

final lifecycleSubscription = Inttegro.instance.paymentSheetEvents.listen(
  (event) {
    switch (event.type) {
      case PaymentSheetEventType.presented:
        onPaymentFlowStarted();
      case PaymentSheetEventType.paymentAttemptStarted:
        onPaymentAttemptStarted();
      case PaymentSheetEventType.paymentAttemptFailed:
        // Recoverable: the native sheet explains the failure and permits retry.
        onPaymentAttemptFailed(category: event.failure!.code);
      case PaymentSheetEventType.paymentActionRequired:
        onPaymentActionRequired(event.action!.type);
      case PaymentSheetEventType.paymentProcessing:
        onPaymentProcessing(event.order!);
      default:
        break;
    }
  },
);

await Inttegro.instance.initializePaymentSheet(
  PaymentSheetConfiguration(
    orderId: orderId,
    returnUrl: Uri.parse('merchant-app://inttegro-return'),
    telemetry: activeTraceContext,
    features: const PaymentSheetFeatures(
      showLineItems: true,
      showInvoiceDownload: true,
      showReceiptDownload: true,
      allowPaymentMethodChange: false,
    ),
  ),
);

try {
  final result = await Inttegro.instance.presentPaymentSheet();

  switch (result) {
    case PaymentSheetCompleted(:final order):
      onPaymentCompleted(order: order);
      await merchantBackend.verifyOrderPayment(order.id);
    case PaymentSheetCanceled():
      onPaymentCanceled();
    case PaymentSheetFailed(:final failure):
      onPaymentSheetFailed(failure);
  }
} finally {
  await lifecycleSubscription.cancel();
}

Optional feature states

Pass PaymentSheetFeatures through PaymentSheetConfiguration.features to control what the native sheet presents. These properties cannot change the Order, its shipping address, its amount, or the customer that owns an attached payment method. Start with the defaults, then add only the context or follow-up actions that make the payment easier to understand.

Property	Default	What changes
`allowPaymentMethodChange`	`true`	Set to `false` to keep an attached method selected and remove the replacement action. If the Order has no attached method, the payer can still enter one.
`showInvoiceDownload`	`false`	Offers the invoice after a successful payment when Checkout returns a secure invoice URL.
`showLineItems`	`false`	Offers a collapsed Order summary when Checkout returns line items. Opening it moves the sheet to its full-height detent before revealing the items.
`showReceiptDownload`	`false`	Offers the receipt after a successful payment when Checkout returns a secure receipt URL.

The opening capture combines showLineItems: true with allowPaymentMethodChange: false. The attached method and pay action remain in view while the Order summary stays out of the way until the payer opens it. The completion capture enables both download properties. After payment succeeds, the sheet returns to its compact height and shows only the document actions for URLs Checkout actually supplied; the primary exit action remains immediately available.

iOS
Android

2 steps

Light mode. Native Inttegro payment sheet on iOS offering a collapsed one-item Order summary above a fixed attached MTN Mobile Money account. — iOSLight
**`showLineItems` with a fixed method**`allowPaymentMethodChange` is `false`, so the attached account stays visible without a replacement action. The summary expands the sheet only when the payer opens it.

Light mode. Native Inttegro payment sheet on iOS confirming payment and offering invoice and receipt download actions. — iOSLight
**`showInvoiceDownload` + `showReceiptDownload`**After a successful payment, available Checkout URLs become secure download actions while the success sheet returns to its compact height.

Every lifecycle event includes type, occurredAt, flowId, and sequence. The complete event set is presented, ready, change, orderPrepared, paymentAttemptStarted, paymentActionRequired, paymentProcessing, paymentAttemptFailed, completed, canceled, and failed. Events about an Order carry its full client-safe representation; there is no separate payment ID. presentPaymentSheet returns the exact terminal event already delivered to the lifecycle stream.

The callbacks above belong to your application; replace them with state updates, analytics, or navigation appropriate to your checkout. A recoverable payment attempt failure does not resolve presentPaymentSheet, because the customer can retry inside the sheet. The SDK owns confirmation, provider authorization, and redirects while your app can use the sanitized events for timely UI and analytics. A secret Inttegro API key must never be included in the application bundle.

Verify before fulfillment

PaymentSheetCompleted is suitable for immediate client UI, but the mobile app is not the authoritative payment source. Your backend must confirm the owner-scoped Order state—using an Order lookup or webhook—before releasing goods or services.

See it in a complete app

The Flutter storefront demo shows a shopper choosing a product and paying through Inttegro's native payment sheet. Follow the guide to run the mobile app with its Next.js demo backend and see where the product, price, order, and credential responsibilities belong.

Observability

Use paymentSheetTelemetryEvents only when you want low-level Checkout and network diagnostics:

import 'package:inttegro_flutter/telemetry.dart';

final diagnostics = Inttegro.instance.paymentSheetTelemetryEvents.listen(
  recordInttegroDiagnostic,
);

paymentSheetEvents provides typed, application-facing stages for each presentation. Use it for checkout UI, analytics, and recoverable-attempt notifications. The terminal result returned by the presentation method remains the source for completion, cancellation, and terminal-failure handling.

paymentSheetTelemetryEvents is the separate diagnostic stream. It adds Checkout operation, HTTP status, safe request identifier, and bounded error-category fields for your application-owned telemetry pipeline. Diagnostic events are not authoritative payment state.

You can pass the active W3C trace context traceparent and optional tracestate when initializing the sheet. Inttegro does not install an exporter or send the event stream anywhere by itself.

Event data-safety contract

Lifecycle and diagnostic events contain bounded status and correlation metadata. They never contain order or payment IDs, customer or payer data, payment-method details, request or response bodies, redirect URLs, or raw error messages. Do not use flowId or requestId as metric labels.

The umbrella package:inttegro_flutter/inttegro_flutter.dart library remains supported for existing applications. The focused libraries organize payment presentation, lifecycle events, and telemetry into responsibility-based API pages while delegating to the same native SDK and release version.