--- title: "Flutter SDK" description: "Integrate and observe Inttegro’s native payment sheet from Flutter." canonical: "https://studio.inttegro.com/mobile/flutter" format: inttegro-machine-docs/v1 language: "PHP" sdk_version: "v12.0.0" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/php/readers/index.json" reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations." preamble_estimated_tokens: 523 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "curated" recommended_mcp_tools: ["design_integration","check_integration_readiness"] estimated_tokens: 3384 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Flutter presents the published native mobile-money Checkout sheet from a backend-created Order ID, with server lookup required after a client-side completed result. ### Five questions #### Q1. Which payment methods does the current Flutter adapter expose? The [Flutter guide](https://studio.inttegro.com/machine/php/mobile/flutter.md) documents mobile money for this version; do not promise cards, Apple Pay, or Google Pay through this adapter. Install the published package and rebuild the app so its native plugin loads. #### Q2. Which data may the mobile app receive? Only the backend-finalized Order ID needed to present Checkout. Keep the API secret, economic calculations, and protected payment details on the backend or in secure Checkout. See [payment lifecycle](https://studio.inttegro.com/machine/php/mobile/flutter.md#payment-lifecycle). #### Q3. How should the sheet be invoked? Initialize PaymentSheetConfiguration with the Order ID, subscribe to lifecycle events, then present the sheet. A hot reload alone does not load a newly added native plugin; rebuild after installation. See [present the sheet](https://studio.inttegro.com/machine/php/mobile/flutter.md#present-the-payment-sheet). #### Q4. Does PaymentSheetCompleted establish a paid sale? No. Use it for immediate UI, then ask the trusted backend to [look up current order state](https://studio.inttegro.com/machine/php/api/orders.md#lookup-an-order) before fulfillment. Canceled and failed result types should be handled distinctly. #### Q5. Where can an agent get a first integration plan? With an authenticated MCP connection, [design_integration](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#design_integration) can specify the Flutter/backend checkout boundary, while [check_integration_readiness](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#check_integration_readiness) audits declared controls. Do not borrow the preview-only [React Native guide](https://studio.inttegro.com/machine/php/mobile/react-native.md) for Flutter symbols. ## Document content # Inttegro SDK for Flutter The [Inttegro SDK for Flutter](https://github.com/inttegro/inttegro-sdk-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. :::tip Start with MCP Before writing SDK code, [connect your MCP client](https://studio.inttegro.com/machine/php/inttegro-mcp/connect.md) and ask MCP to [design the integration](https://studio.inttegro.com/machine/php/inttegro-mcp/design-integration.md) for your mobile checkout flow. Use the resulting plan to define the boundary between your server, this SDK, and the Inttegro API. ::: :::note 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](https://docs.flutter.dev/install) or later and Dart 3.12 or later - [iOS 16](https://developer.apple.com/documentation/ios-ipados-release-notes) or later - [Android API 26](https://developer.android.com/tools/releases/platforms) 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: ```shell flutter pub add inttegro_flutter ``` [Hot reload](https://docs.flutter.dev/tools/hot-reload) cannot add a newly installed native plugin to a running application. ## Payment lifecycle > Mobile Payment Lifecycle is interactive content. Use the canonical page to view it. 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. ```dart 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`: ```dart 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. > Mobile Sdk Screenshots is interactive content. Use the canonical page to view it. ## Present the payment sheet ```dart 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`](https://flutter.inttegro.dev/v0.5.0/inttegro_flutter/PaymentSheetFeatures-class.html) 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`](https://flutter.inttegro.dev/v0.5.0/inttegro_flutter/PaymentSheetFeatures/allowPaymentMethodChange.html) | `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`](https://flutter.inttegro.dev/v0.5.0/inttegro_flutter/PaymentSheetFeatures/showInvoiceDownload.html) | `false` | Offers the invoice after a successful payment when Checkout returns a secure invoice URL. | | [`showLineItems`](https://flutter.inttegro.dev/v0.5.0/inttegro_flutter/PaymentSheetFeatures/showLineItems.html) | `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`](https://flutter.inttegro.dev/v0.5.0/inttegro_flutter/PaymentSheetFeatures/showReceiptDownload.html) | `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. > Mobile Sdk Feature Screenshots is interactive content. Use the canonical page to view it. 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](https://studio.inttegro.com/machine/php/api/authentication.md#store-credentials-safely) must never be included in the application bundle. :::warning 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](https://studio.inttegro.com/machine/php/demos/flutter.md) 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: ```dart import 'package:inttegro_flutter/telemetry.dart'; final diagnostics = Inttegro.instance.paymentSheetTelemetryEvents.listen( recordInttegroDiagnostic, ); ``` > Mobile Sdk Observability is interactive content. Use the canonical page to view it. 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. ## Continue - [Browse the generated API reference](https://flutter.inttegro.dev/v0.5.0/) - [Browse the package source](https://github.com/inttegro/inttegro-sdk-flutter) - [Run the Flutter storefront](https://studio.inttegro.com/machine/php/demos/flutter.md) - [Create and finalize orders](https://studio.inttegro.com/machine/php/api/orders.md#create-an-order)